Troubleshooting Updates
This information only applies to self-hosted WHMCS installations. WHMCS Cloud updates WHMCS for you automatically.
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.
Checking for Updates
For more information, see Prepare to Update WHMCS.
You may encounter the following common issues:
| Error or Issue | Cause | More Information |
Unable to Perform Automatic Updates | This error can have many causes. | Automatic Updates Unavailable |
Check for Updates Failed | This error can have many causes. | Check for Updates Failures |
Make certain that you have selected a valid Update Channel and then try again | You have not correctly configured the Update Channel setting. | Update Channel Errors |
Update Errors and Failures
You may encounter the following common issues:
| Error or Issue | Cause | More Information |
You are attempting to access the admin area via a directory that is not configured. or You are attempting to access the admin area via a directory that is different from the one configured. or You are attempting to access the admin area via a custom directory, but we have detected the presence of a default "admin" directory too. or The request path cannot be resolved. | You are attempting to access the wrong directory, there is a problem in your admin path configuration, or your admin directory is out-of-date. | Admin Directory Errors |
| The Admin Dashboard appears blank and widgets will not load. | There may be a problem with your system’s table collation values. | Blank Admin Dashboard |
Server Command Error - Curl Error - 28 connect() timed out or cURL error 28: Operation timed out | An operation timed out due to a connection issue. | cURL Timeout Errors |
Down for Maintenance (Err2) | There is a mismatch between the database version and WHMCS version or PHP version. | Down for Maintenance Errors |
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 |
Error: failed to open stream: operation failed | The application is unable to confirm the validity of the SSL certificate. | File Download Errors |
| Admins cannot access database backups, storage settings, or updates on WHMCS Cloud installations. | WHMCS Cloud automatically manages certain system functions. | Missing Features on WHMCS Cloud |
Network Issue - Failed Communication with Update Server | This error indicates that your server could not connect to our update server. | Network Issue Errors |
| The most recent WHMCS release does not display when you check for available updates. | The page did not refresh, your settings exclude the new version, or your system does not meet the minimum requirements. | New Version Not Appearing |
no existing installation was detected or WHMCS Not Installed Error | The configuration.php file is not in the expected location, it is not readable, or it does not contain the details for your MySQL® database. | No Existing Installation Errors |
Apply update dry-run detected x permission issues | Existing file permissions are incorrect. | Update Dry Run Errors |
Update Failed An error occurred that prevented the update from completing successfully. | You can find the cause of the issue by examining the full output below the error message. | Update Failed Errors |
Update Message Validation Issue This update contains notification messages that WHMCS could not validate. | Cryptographic validation is failing. | Update Message Validation Errors |
Unattended Automatic Updates
For more information, see Unattended Automatic Updates.
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 |
After Updating
You may encounter the following common issues:
| Error or Issue | Cause | More Information |
Updater unable to add default database tls options to configuration file: Application configuration file is not writable | The permissions for the configuration.php file prevented the update process from adding new placeholder entries. | Application Configuration Errors |
| After applying an update, some WHMCS features do not function normally, display errors, display with poor formatting, or do not display at all. | In most cases, this behavior is due to outdated customized template files. | Feature Issues After Update |
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 | There are files from an earlier version of WHMCS in the /admin directory. | GuardedForUpdate Errors |
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 |
No Connection | There is a problem preventing your server from communicating with the WHMCS licensing server. | No Connection Errors |
Last modified: 2026 September 30