Troubleshooting PHP
If you encounter errors or issues with PHP in your WHMCS installation, see the sections below to start troubleshooting and resolve the issue.
- For more information, see PHP Errors and Exceptions and PHP Version Compatibility.
- For general steps to troubleshoot problems in WHMCS, see Start Troubleshooting.
PHP Errors
WHMCS may return PHP errors and exceptions if errors occur. PHP errors can vary from informative to critical. For example:
- The insensitive
E_ERRORandE_PARSEtypes indicate that there is a critical problem interpreting the code. - The hyper-sensitive
E_STRICTtype indicates that there’s a code instruction that may trigger ancillary contexts that the developer should note for cross-compatibility against PHP versions or incorporated libraries. However, it does not indicate an error.
Depending on the error type, it may be possible to suppress the error and continue the current code path. For critical errors types like E_ERROR and E_PARSE, it is not possible continue the current code path since it explicitly represents non-functional code and there is no viable alternative path available.
Exceptions
Ideally, all code that emits an exception will have surrounding code that can observe the exceptional condition and take a valid, user-friendly path. If this is not possible, then PHP will continue to revert control, all the way back to the originally-called script. If the original script cannot observe the exception, it becomes an uncaught exception and will behave like a critical error.
Handlers
If the system invokes an uncaught exception or error condition (based on the error reporting level), PHP will attempt to execute any registered handlers that PHP defined before the condition occurred. The handlers provide a last minute opportunity to affect how to report the condition. They do not have the power to mitigate the condition or revert to an alternative code path.
WHMCS registers various error and exception handlers as soon as possible so that if such a condition occurs, there’s a final opportunity to output a friendly message. If the condition happens before WHMCS has the opportunity to register its handlers, such as missing or corrupt core files or an invalid environment, the result will be the behavior that the server defines (for example, php.ini file and Apache® settings).
Common Errors
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
500 Internal Server Error | There was a problem while processing a request. | 500 Internal Server Errors |
Allowed memory size of xxxxx bytes exhausted (tried to allocate xxxx bytes) | WHMCS has reached maximum amount of memory available to PHP on your server. | Allowed Memory Exhausted Errors |
Down for Maintenance (Err2) | There is a mismatch between the database version and WHMCS version or PHP version. | Down for Maintenance Errors |
PHP Fatal error: Class 'xxxx' not found in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/Exception/Handler/ExceptionLoggingTrait.php on line 0 | A core WHMCS file is missing. | ExceptionLoggingTrait 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 |
Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 20480 bytes) | The system is terminating the cron job because it has exceeded the memory_limit value of 32 MB. | Fatal Memory Size Errors |
| Admins or users report that the system frequently logged them out. | You have misconfigured PHP, a proxy, or CDN on the server that hosts WHMCS, there is insufficient disk space, or there is a problem with the visitor’s IP address. | Frequent Logouts |
InvalidArgumentException: Data missing in /path/to/whmcs/cs/vendor/nesbot/carbon/src/Carbon/Carbon.php:425 | Your system’s PHP version is not compatible with your current WHMCS version. | InvalidArgumentException Carbon 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 |
Legacy Smarty Tags: The system detected that legacy Smarty tags may be in use and that the Allow Smarty PHP Tags setting is enabled. | A theme or email template contains deprecated code or you have enabled Allow Smarty PHP Tags. | Legacy Smarty Tag Errors |
A license key is required. If you don't have one, please visit www.whmcs.com to purchase one. | There is an issue with the PHP sessions configuration in your server environment. | License Key Required Errors |
| When a user downloads a PDF invoice in the Client Area, the system logs them out. | pdo_mysql clients in your server configuration caused unexpected behavior in PHP. | Logout During Invoice Download |
Unable to find the socket transport "ssl" | There is a problem with PHP on your server. | Nominet Socket Transport Errors |
| You are experiencing problems that relate to stale cached data or PHP script execution. | The OPcache PHP extension is enabled. | OPcache Warnings |
PHP Fatal error: Maximum execution time of 300 seconds exceeded in /path/to/file.php | The max_execution_time limit is too low for a specific task or operation. | PHP Execution Time Errors |
Required function is not available or Required function base64_decode is not available | This error indicates that a necessary function is not installed on the server or is disabled in the configuration. | Required Function Errors |
Segmentation fault | This error does not directly relate to the WHMCS software and can occur for many different reasons. | Segmentation Fault Errors |
| The system is not removing sessions from the location in your session configuration. | There is a problem in your PHP configuration. | Sessions Are Not Removed |
| 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 |
An Error Occurred. Please try again. | The server environment is missing the expected nd_pdo_mysql PHP extension. | Stripe Try Again Errors |
| The installation process became stuck on Step 4. | Your system or its configuration do not meet our system requirements. | Stuck Installation Process |
| You experience timezone-related issues in WHMCS or while running WHMCS automation. | There is a timezone misconfiguration or a mismatch between the webserver’s PHP configuration and the cron engine’s PHP configuration. | System Timezone Issues |
Call to undefined function PHPMailer/
HPMailer/scapeshellarg() in /path/to/whmcs/vendor/phpmailer/phpmailer/src/PHPMailer.php:1730 | The escapeshellarg function is disabled in your server’s PHP configuration. | Undefined PHPMailer Function Errors |
Whoops\Exception\ErrorException Maximum execution time of 30 seconds exceeded | The system is terminating the cron job because it has exceeded the max_execution_limit value of 30 seconds. | Whoops Exception Errors |
TypeError Errors
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
TypeError: array_search(): Argument #2 ($haystack) must be of type array, null given in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/Cron/Task/EmailMarketer.php:0 | An invalid value in the Email Marketer rule (a missing billing cycle) causes an error in PHP 8.1 environments only. | Email Marketer TypeErrors |
TypeError: Argument 3 passed to WHMCS\Domains\AdditionalFields::processFieldOverrides() must be of the type array, null given, called in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/Domains/AdditionalFields.php | There is a syntax error in the /resources/domains/additionalfields.php file. | TypeError AdditionalFields Errors |
TypeError: Return value of convertIniSize() must be of the type int Error, float returned in /path/to/whmcs/includes/functions.php | The PHP configuration that WHMCS uses contains an invalid post_max_size value. | TypeError covertIniSize Errors |
TypeError: Return value of WHMCS\File::guessFileExtension() must be of the type string, null returned in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/File.php | The fileinfo function is missing or disabled in your server’s PHP configuration. | TypeError guessFileExtension Errors |
Last modified: 2025 January 29