Unattended Automatic Updates
WHMCS can apply maintenance releases automatically on a schedule that you set, back up the files it replaces before each update, and restore your previous version if the update fails.
You can configure this feature at Utilities > Update WHMCS, by clicking Configure Update Settings.
How the Update Process Works
A maintenance release increments only the last segment of the version number (for example, WHMCS 9.1.0 to WHMCS 9.1.1). Maintenance releases contain bug fixes and do not introduce new features.
When you enable unattended automatic updates, the system:
- Checks for an available maintenance release.
- Compares the release against your configured schedule.
- Creates an update record.
- Displays the record in the Update History table with a Scheduled status.
- Downloads the update.
- Backs up the files it will replace when the scheduled time arrives.
- Applies the update.
- Records the status as Completed or Failed.
- Sends an email to admins.
- Displays a notification in the Admin Area.
Requirements
Unattended automatic updates use the same system requirements as manual automatic updates. In addition, the user under which WHMCS runs must have read, write, and execute permissions on the WHMCS installation’s directory and all of its files and subdirectories, not just the writeable directories that manual updates use.
Backups and Rollbacks
Immediately before it applies an update, the system backs up only the files that the update will replace and stores the archive at tools/AutoUpdates/backups/backup-<version>.zip. This backup does not include your database or any other files, and the system deletes the previous backup when it creates a new one. The system names the archive using the tag for the release it is installing: for example, backup-9.1.1-release.1.zip contains the files as they existed before the system applied the 9.1.1-release.1 update.
If the update fails after the system begins applying it, the system restores the replaced files from this backup and returns your installation to its previous version.
Retry Behavior
The system attempts an update up to three times: the initial attempt plus two retries. Between attempts, the record’s status returns to Scheduled. It changes to a permanent Failed status only after the third failed attempt, and the system does not retry that version again. The next attempt starts on the next run of the Automatic Update Run system cron task, which by default runs within five minutes, regardless of your configured schedule.
A fatal error while the system prepares the patch sets the record to the Failed status immediately, with no retries. If a run stops responding, the system waits 30 minutes before counting that run as one of the three attempts.
Permissions
To configure unattended automatic updates, your administrator role must include the following permissions:
- Update WHMCS
- Modify Update Configuration
- Unattended Automatic Updates
Configuring the Schedule
You can configure the frequency, day, and time for unattended automatic updates from Configure Update Settings.
Update History
The Update History table at Utilities > Update WHMCS lists every automatic update that the system attempted. It displays the date of the attempt, the version that the system applied, and the status.
The table displays the following statuses:
| Status | Description |
|---|---|
| Scheduled | The system found an available maintenance release and will apply it at your next scheduled time. |
| In Progress | The system is downloading or applying the update. |
| Completed | The system applied the update successfully. |
| Failed | The update did not finish. For more information, see Troubleshooting below. |
Update Notifications
The system notifies admins whose administrator roles have the System Emails permission about the outcome of automatic update attempts, in the Admin Area and by email.
Troubleshooting
tools/AutoUpdates/logs/auto-update.log instead of the Activity Log.You may encounter the following common issues with unattended automatic updates:
| Error or Issue | Cause | More Information |
The system failed to fetch the packages.json file: the response was empty. Check your CDN connectivity. | This error indicates that your server could not reach the WHMCS content delivery network to retrieve the list of available updates. | Automatic Update Connectivity Errors |
The system failed to write the temporary repository file: <path>, The permission check failed: the system cannot write to <directory>, The permission check failed: the system cannot write to backup directory <directory> (operation: backup), The permission check failed: the system cannot read <file> (operation: backup), The permission check failed: the system cannot write to <file> (operation: apply), The permission check failed: the system cannot create directory <directory> (operation: apply), or The permission check failed: the system cannot read the patch archive <file> (operation: apply) | These errors indicate that the user under which WHMCS runs does not have the permissions it needs for this step of the update. | Automatic Update Permission Errors |
The version field is missing for <version> in the packages.json patches section. | This error indicates that the packages.json entry for this release is missing required version data. | Automatic Update Version Data Errors |
Version 9.1.1 not found in packages.json patches section | This error indicates that the system found this maintenance release when it last checked for updates, but the release was no longer listed when the system attempted the download. | Automatic Update Version Unavailable Errors |
| An unattended automatic update record shows a permanent Failed status in the Update History table and the system stops retrying that version. | This failure occurs after the system exhausts its retry attempts for a maintenance release. | Permanent Automatic Update Failures |
Last modified: 2026 September 30