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 IssueExplanationNext 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 UpdatesThis error can occur for many reasons. The specific issue will appear under the error.Automatic Updates Unavailable
Check for Updates FailedThis 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 IssueExplanationNext Steps
A fatal error occurred while fetching the updateThis error may occur due to issues with PHP, your server, or your network.Fatal Error Fetching Update
Apply update dry-run detected x permission issuesThis error indicates a permissions issue.Update Dry Run Errors
cURL error 28: Operation timed outThis 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 downloadedThe application is unable to confirm the validity of the SSL certificate.File Download Errors
Network Issue - Failed Communication with Update ServerYour server could not connect to our update server.Network Issue Errors
no existing installation was detectedThe 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 Failed
An 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 Issue
This 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 IssueExplanationNext 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 writableThe 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:0This is caused by the presence of files from an earlier version of WHMCS in the /admin directory.GuardedForUpdate Errors

Last modified: June 14, 2024