General Troubleshooting

If you encounter errors or issues while working with WHMCS, see the sections below to start troubleshooting and resolve the issue.

Display Issues and Accessing WHMCS

You may encounter the following common issues:

Error or IssueExplanationNext Steps
Accented characters do not display correctly in CSV reports.This issue is due to a limitation of Microsoft® Excel’s handling of these characters and filetypes.Character Display in Reports
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
Individual pages of WHMCS are missing content.The template file for the page is missing or contains a syntax error.Empty Pages
The Admin Dashboard appears blank and widgets will not load.There may be a problem with the table collation values.Blank Admin Dashboard
You encounter a blank or partially-rendered page.This issue indicates that a fatal PHP error is occurring.Blank or Partially-Rendered Pages
You encounter a redirect loop.This issue is usually due to misconfiguration of your website or server.Redirect Loops
404 Not Found: The requested URL was not found on this server.The URL generates an SEO-friendly link instead of a link using variables (for example, index.php?rp=/admin/setup) or you have an outdated .htaccess file.404 Page Not Found Errors
An error occurred while communicating with the server. Please try againThe URL that you are using to access WHMCS does not match the WHMCS System URL setting.System URL Mismatch Errors
Down for Maintenance (Err2) An upgrade is currently in progressIf an update is not currently in progress, this indicates a version mismatch between the PHP files and the MySQL® database.Down for Maintenance Errors
InvalidArgumentException: Dataset must be an array in /vendor/whmcs/whmcs-foundation/lib/TableQuery.phpThe mysql_charset value is incorrect in the configuration.php file.Dataset Must Be Array Errors
Oops! errors.WHMCS returns Oops! errors for many reasons. For example, an Oops! error message when you view the list of addon modules may be due to an incompatible module.Oops! 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.
The $customadminpath value is invalid in the WHMCS configuration.php file, you are attempting to access the wrong directory, or a recent update uploaded files to the default admin directory.Admin Directory Errors

Files and ionCube Encoding Errors

You may encounter the following common issues:

Error or IssueExplanationNext Steps
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 0This error indicates a PHP version encoding error due to outdated file for a previous WHMCS version.ionCube Fatal Decoding Errors
File Not FoundThis error indicates that 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:106This error is reporting that the system cannot read or write to the storage location for email attachments.Impossible root Errors
main(): Failed opening required '/path/to/whmcs/..filename.php'...A required file is missing.Failed Opening 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 on your server. It might be outdated or missing entirely.ionCube Loader Site Errors
The file /home/username/public_html/whmcs/modules/gateways/paypalexpress.php encoded as type [1/71] cannot be decoded by this version of the ionCube Loader. in Unknown on line 0This error occurs because a file is not compatible with your version of ionCube Loader®.File Cannot Be Decoded Errors
The file /path/to/whmcs/index.php is corrupted.Your version of ionCube Loader® does not meet WHMCS’s system requirements or the file is unreadable because something modified it.Corrupt File Errors

Other Errors

You may encounter the following common issues:

Error or IssueExplanationNext Steps
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
An unknown error occurredThis error is due to a third-party system or module providing 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:386A bot is crawling your website and trying to access an invalid URL.Query String URI Errors

Last modified: June 11, 2024