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 | Next Steps |
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 | Next Steps |
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 |
Fatal error: The file /home/username/public_html/whmcs/modules/gateways/ewayuk.php was encoded by the ionCube Encoder for PHP 5.3 and cannot run under PHP 7.0. Please ask the provider of the script to provide a version encoded with the ionCube Encoder for PHP 5.6. in Unknown on line 0 or The file /vendor/whmcs/whmcs-foundation/lib/Installer/Composer/Hooks/ComposerInstallerHook.php was encoded by the ionCube Encoder for PHP 5.6 and cannot run under PHP 7.1 or later. Please ask the provider of the script to provide a version encoded with the ionCube Encoder for PHP 7.1. or PHP Fatal error: The file /vendor/whmcs/whmcs-foundation/lib/Installer/Composer/Hooks/ComposerInstallerHook.php encoded as type [1/72] cannot be decoded by this version of the ionCube Loader.gi | There is a PHP version encoding error due to outdated file for a previous WHMCS version. | ionCube Fatal Decoding Errors |
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 |
After Updating
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
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 |
Last modified: 2025 October 17