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.
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 July 28