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.
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: June 14, 2024