General Troubleshooting
If you encounter errors or issues while working with WHMCS, see the sections below to start troubleshooting and resolve the issue.
- For general steps to troubleshoot problems in WHMCS, see Start Troubleshooting.
- For steps for additional Client Area-specific issues, see Troubleshooting the Client Area.
General Errors
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
404 Not Found: The requested URL was not found on this server. | There is a problem in your Friendly URLs configuration or your .htaccess file is out-of-date. | 404 Page Not Found Errors |
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 |
InvalidArgumentException: Dataset must be an array in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/TableQuery.php:0 Stack trace: #0 /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/TableModel.php(0): WHMCS\TableQuery->setData(NULL) | The $mysql_charset value is incorrect in the configuration.php file. | Dataset Must Be Array Errors |
Down for Maintenance (Err2) | There is a mismatch between the database version and WHMCS version or PHP version. | Down for Maintenance Errors |
You created a custom /resources/country/countries.json file, but the expected changes do not occur. | The file contains an invalid syntax. The file must contain valid JSON syntax. | Missing Country Customizations |
An unknown error occurred | A third-party system or module provided a response that WHMCS cannot recognize or interpret. | Module Command Unknown Errors |
InvalidArgumentException: Query string must not include a URI fragment in /path/to/whmcs/vendor/zendframework/zend-diactoros/src/Uri.php:386 | A bot is crawling your website and trying to access an invalid URL. | Query String URI Errors |
| You experience redirect loops while attempting to use WHMCS. | Your server or website is misconfigured. | Redirect Loops |
An error occurred while communicating with the server. Please try again | A problem is preventing communication with the WHMCS server. | Server Communication Errors |
| The final column in your system’s log entries contains the server IP address instead of the admin’s or client’s IP address. | The IP address that the server configuration is supplying to PHP is incorrect. | Server IP Address in Logs |
Display Issues
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
| 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 |
| The Choose a Domain page is blank in the Client Area. | You have not enabled any domain registration options. | Blank Choose a Domain Page |
| A domain search returns no results and renders a blank page. | The system encountered an incorrect response type. | Blank Domain Search Results |
| The system automation tasks are generating completely blank invoices. | Multiple cron jobs are attempting to run the system cron at the same time. | Blank Invoices |
| You encounter a blank or partially-rendered page. | There is a fatal PHP error, a problem with a module or template, or a problem with ionCube Loader®. | Blank or Partially-Rendered Pages |
| You see a blank page while attempting payment using a payment gateway module. | There are two copies of the same file in the modules/gateway directory. | Blank Payment Gateway Page |
| Accented (Unicode) characters are displaying incorrectly in reports. | This issue is due to a limitation of Microsoft Excel’s handling of these characters and filetypes. | Character Display in Reports |
| The primary navigation bar and sidebar menu items do not display correctly. | The language file that contains the text for these menu items is missing, unreadable, or corrupted. | Client Area Title Display Issues |
| Pages in WHMCS are empty or content is missing. | A template file is missing or contains a syntax error. | Empty Pages |
| 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 |
Invalid Access Attempt | You are using the wrong URL to access the WHMCS Admin Area. | Invalid Access Attempt 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 |
| Clicking Order Now or following a direct product order link refreshes the page and shows the product selection page again. | There is a problem with the URL or a template is out-of-date. | Order Now Refreshes the Page |
| The uptime or CPU load statistics for a server are not displaying properly. | The server does not use a Linux®-based operating system, the status directory is inaccessible, or required PHP functions are disabled. | Status Monitoring Display Issues |
| When a user attempts to check out from the shopping cart, the system redirects them to the wrong page. | This issue is due to a problem with the customizations in your header template. | User Redirected to Wrong Page |
Files and ionCube Encoding Errors
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
The file /path/to/whmcs/index.php is corrupted. | You are not using the required minimum version of ionCube Loader® or the file is unreadable. | Corrupt File Errors |
Oops! main(): Failed opening required '/path/to/whmcs/filename.php'... | A required file is missing. | Failed Opening Errors |
The file /home/username/public_html/path/to/whmcs/filename.php encoded as type [1/71] cannot be decoded by this version of the ionCube Loader. in Unknown on line 0 | A file is not compatible with your version of ionCube Loader®. | File Cannot Be Decoded Errors |
File Not Found | A file is not present or is not accessible at the expected location. | File Not Found Errors |
League\Flysystem\Exception: Impossible to create the root directory "/folder/path". in /path/to/whmcs/vendor/league/flysystem/src/Adapter/Local.php:106 | The system cannot read or write to the storage location for email attachments. | Impossible root 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 | There is a PHP version encoding error due to outdated file for a previous WHMCS version. | ionCube Fatal Decoding Errors |
Site error: the ionCube PHP Loader needs to be installed. This is a widely used PHP extension for running ionCube protected PHP code, website security and malware blocking. Please visit get-loader.ioncube.com for install assistance. or Site error: the file /path/cron.php requires the ionCube PHP Loader loader to be installed. | There is a configuration problem with ionCube Loader®. | ionCube Loader Site Errors |
Last modified: 2025 March 13