Troubleshooting Updates
If you encounter errors or issues while updating WHMCS versions, see the sections below to start troubleshooting and resolve the issue.
- For more information, see Updating WHMCS.
- For general steps to troubleshoot problems in WHMCS, see Start Troubleshooting.
Before Updating
For more information, see Prepare to Update WHMCS.
You may encounter the following common issues:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
| New versions are not appearing at Utilities > Update WHMCS. | Your system does not meet the system requirements for the new version. | New Version Not Appearing |
Update Now is disabled and the page displays Unable to Perform Automatic Updates | This error can occur for many reasons. The specific issue will appear under the error. | Automatic Updates Unavailable |
Check for Updates Failed | This error may occur due to connectivity issues, a PHP version mismatch, or a problem with your Temporary Update Path setting. | Check for Updates Failures |
Update Errors and Failures
You may encounter the following common issues:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
A fatal error occurred while fetching the update | This error may occur due to issues with PHP, your server, or your network. | Fatal Error Fetching Update |
Apply update dry-run detected x permission issues | This error indicates a permissions issue. | Update Dry Run Errors |
cURL error 28: Operation timed out | This error indicates that the server was unable to download the .zip file before it reached your server’s connection timeout limit. | Update Timed Out Errors |
File could not be downloaded | The application is unable to confirm the validity of the SSL certificate. | File Download Errors |
Network Issue - Failed Communication with Update Server | Your server could not connect to our update server. | Network Issue Errors |
no existing installation was detected | The configuration.php file is not in the expected location, it is not readable, or does not contain the details for your MySQL® database. | No Existing Installation Errors |
Update FailedAn error occurred that prevented the update from completing successfully. | This error may be due to many casues. Examine the full output below the error message to find the issue. | Update Failed Errors |
Update Message Validation IssueThis update contains notification messages that WHMCS could not validate. | This message indicates that cryptographic validation is failing. | Update Message Validation Errors |
WHMCS\Exception\Application\InstallationVersionMisMatch: Database version '8.6.2-release.1' does not match file version '8.7.1-release.1' | There is a mismatch between the database version and WHMCS version. | Down for Maintenance Errors |
After Updating
You may encounter the following common issues:
| Error or Issue | Explanation | Next Steps |
|---|---|---|
| After applying an update, some WHMCS features do not function or display normally. | You did not apply template changes for your new WHMCS version and any intermediate versions before update. | Feature Issues After Update |
A recent WHMCS update failed to remove legacy modules. These modules may cause negative behavior if you upgrade PHP and leave them on the system. | The Automatic Updater utility was unable to remove one or more discontinued and unused modules. | Legacy Module Removal Errors |
Updater unable to add default database tls options to configuration file: Application configuration file is not writable | The file permissions for the configuration.php file are incorrect. | Application Configuration Errors |
WHMCS\Exception\Model\GuardedForUpdate: The "WHMCS\Config\Setting" record "setting" property is guarded against updates in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/Model/Observer.php:0 | This is caused by the presence of files from an earlier version of WHMCS in the /admin directory. | GuardedForUpdate Errors |
Last modified: January 8, 2025