Troubleshooting — the Securantis agent: update failed

Goal

This article explains how to diagnose and fix a failed Securantis agent update on WordPress/WooCommerce or PrestaShop. It covers license checks, permissions, ZIP integrity, disk space, rollback procedures and the information to provide to support.

Prerequisites and general precautions

• Have FTP/SFTP or SSH access to the server and, if necessary, access to the CMS administration area.
• Never send passwords by e-mail or chat. Use the secure client area to share temporary access after contracting a paid intervention.
• Perform a full backup of files and the database before any manipulation (file operations can make the site unavailable).
• Quarantine, restoration or deletion of suspicious files requires a human decision; Securantis does not automatically delete malicious files.

Initial checks (to perform before any modification)

1. Check the license status

• Confirm that the license attached to the site is active and has not reached its site quota. An inactive or unlinked license will often prevent private updates.
• If you recently changed the domain or cloned the site, properly detach/attach the license via the Securantis administration area or the SaaS.

2. Check disk space

• Ensure the partition containing the webroot has enough free space. ZIP extraction and temporary backups require space (allow at least 50–100 MB free for small to medium sites, more depending on ZIP size).

3. Check file and folder permissions

• The web server user must be able to write to the folders where the agent is installed as well as to temporary folders used to extract ZIPs. If you use FTP/SFTP, verify that the technical user has write permissions.
• For WordPress: check that the folder containing the plugin is writable by the web process (or by the CLI user if you use WP-CLI).
• For PrestaShop: check that the module folder and the temporary modules folder are writable.

4. Integrity of the update ZIP file

• If the update comes from a manual upload, the ZIP may be corrupted. Download the ZIP again from the Securantis client area and compare size/hash if possible.
• Avoid trying to open the ZIP on the server with limited tools: download it locally to verify it opens and contains the expected files.

Troubleshooting steps — WordPress/WooCommerce

1. Reproduce the error and collect logs

• Trigger the update then collect the error messages displayed in the administration, the PHP/server logs and, if available, the agent logs. Note the exact time of the failure.

2. Attempt installation via an alternative method

• If installation via the interface fails, use WP-CLI (if available) to install or update the plugin: this removes issues related to the browser or interface limitations.
• If WP-CLI is not possible, proceed via FTP/SFTP: rename the old plugin folder (e.g. plugin_old), upload and extract the new folder, then check permissions.

3. Check security hooks and WAF

• If a WAF/application firewall blocks the action (rules modifying uploads or execution of PHP scripts), temporarily set the interface to observation mode if possible, or ask the hosting support to allow the operation.

Troubleshooting steps — PrestaShop (1.7 to 9)

1. Observe back-office behavior

• When an update fails via the module management page, note the returned message. PrestaShop sometimes performs checks that prevent extraction if the module ZIP is non-compliant or if permissions are incorrect.

2. Manual installation via FTP/SFTP

• Upload the decompressed module folder into the modules directory. Then check in the administration that the module is detected and proceed with the update from the interface.
• If the module does not appear, clear the theme cache and PrestaShop caches before retrying.

Rollback (reverting to the previous version)

1. Prepare the previous version

• If you have kept a copy of the previously working ZIP or plugin/module folder, prepare it locally.

2. Procedure via FTP/SFTP

• Rename the current agent folder (for example .old) to keep a copy.
• Upload and restore the previous version of the plugin/module.
• Check permissions and restart the web service if necessary.

3. Verification after rollback

• Verify site availability, connection with the Securantis platform and run a test scan.
• Note that some recent settings may not be compatible with the previous version; test critical functionalities (connection, firewall, scan).

Common errors and quick fixes

• Disk space error during extraction: free space (logs, temporary backups), then restart the installation.
• Permission denied when writing files: apply correct permissions for the web user or perform the operation as a user with sufficient rights via SSH.
• Corrupted or incomplete ZIP: re-download from the Securantis client area and verify integrity locally.
• Conflict with another plugin/module: temporarily disable third-party security extensions that may interfere (after backup) and retry.
• Rejected by the WAF: request a temporary relaxation of rules or perform the update outside peak hours after informing the host.

Advanced troubleshooting (if previous actions fail)

• Collect logs: retrieve PHP, Nginx/Apache logs, and any logs provided by the Securantis agent. Note any SQL errors and PHP exceptions.
• Temporary debug mode: enable PHP or CMS debug to obtain a more complete trace (remember to disable it afterwards).
• Check PHP compatibility: ensure the PHP version is compatible with the agent and CMS version (Securantis supports specific ranges — check the compatibility documentation).

When to contact Securantis support and what information to provide

Contact support if:

• You followed the steps above and the update still fails.
• The agent returns internal errors or does not reconnect after the update.
• You suspect a complex conflict with hosting infrastructure (system permissions, SELinux, chroot, readonly FS).

Information to provide to support (useful and speeds up processing)

• Site URL and license identifier (no passwords).
• Timestamp (UTC) of update attempts and retrieved logs.
• Relevant log excerpts (PHP error messages, extraction failure errors, HTTP response if applicable).
• Precise description of actions already performed (rollback attempted, installation methods tried).
• For a paid intervention, never send access by e-mail: use the secure client area and provide access only after agreement and payment.

Careful settings and recommendations

• Test updates on a staging environment when possible.
• Always keep the previous version of the plugin/module for at least 48 hours after a production update to allow a quick rollback.
• Schedule updates outside traffic peaks and inform the host if operations that may be blocked by the WAF are planned.

Expected outcome after correction

• The Securantis agent is updated and reconnects to the SaaS.
• Features (scanner, quarantine, firewall, reports) are available and scans run normally.
• After a rollback, the site returns to its previous functional state and the agent resumes expected behavior.

Final note

Securantis provides private updates and assistance for installation; however, some operations require hosting rights or intervention by the host. If you are not comfortable with server operations, request Securantis support for a guided or scheduled intervention.