Start Troubleshooting

In some cases, you may suspect a problem but not know exactly when or where it occurred in WHMCS. This can make finding the cause difficult. If you can’t find the symptoms in our documentation, the steps below can help you collect details before you contact support.

When you troubleshoot an issue, note the exact steps that you take and their results. If you need to contact WHMCS Technical Support, these details will help us find and address the problem faster.
You can use maintenance mode to stop users from using the Client Area while you work.

The steps below only apply to existing installations. For problems during installation, see Troubleshooting Installation.

Simple Troubleshooting

You can find the cause of most problems using a few basic troubleshooting steps.

1. Check for errors and failures.

WHMCS includes features that can help you find and fix issues quickly. If you suspect a problem, check these locations first.

Log Files

WHMCS suppresses non-critical warnings and errors by default. However, if an error is critical or results in an error page, the system will record it in the logs. The system also records details when you enable error reporting.

Check the logs that relate to your suspected problem:

Log	Location	Related To
Activity Log	Configuration () > System Logs	System events. The actions of individual clients and users. Actions and events that the system performs for individual clients and users.
Admin Log	Configuration () > System Logs	Admin login session information, including: Login and logout times. IP addresses Admin usernames.
Email Message Log	Configuration () > System Logs	All of the emails that WHMCS sends to clients and users except for messages that use the following email templates: Automated Password Reset Client Email Address Verification Password Reset Validation You can disable support ticket reply logging in this log by enabling Disable Reply Email Logging in the Support tab at Configuration () > System Settings > General Settings.
Environment Log	Varies.	Errors and exceptions. Your server environment sets the destination of these log entries. For most servers, this is the Apache® error log. cPanel & WHM logs errors in several locations. For more information, see Where are the PHP error logs located?.
Gateway Log	Billing > Gateway Log	Attempted and completed transactions through payment gateway modules.
Module Log	Configuration () > System Logs	Module-related activity between your WHMCS installation and third-party APIs or other systems. The Module Log only records activity if you have enabled it at Configuration () > System Logs.
Ticket Mail Import Log	Configuration () > System Logs	All of the support ticket emails that WHMCS added to the support ticket system via email piping or email importing. For more information, see Email Piping, Email Importing, and Troubleshooting the Support System.
WHOIS Lookup Log	Configuration () > System Logs	The domains that your customers search for in the Client Area.

For more information, see Logs in WHMCS.

Module Queue

If you suspect that your problem relates to a module, view the list of module actions at Utilities > Module Queue. This list includes failed actions that WHMCS attempted to perform using a module.

You can use this list to retry or dismiss individual errors or retry all of the listed actions.

For more information, see Module Queue.

2. Enable Error Reporting and try again.

If you can’t find a cause in the logs or module queue, you can view more details by enabling the error reporting system in the Other tab at Configuration () > System Settings > General Settings.

Only enable error reporting while you are actively troubleshooting an issue. Disable it as soon as you finish.
Error reporting displays potentially-sensitive error details to anyone who experiences an error. This includes your staff and your customers.

When you enable this, you can easily log and view more information about:

Oops! errors.
Display issues, like blank or partially-rendered pages.
Some PHP errors.
Some system cron issues.
Database errors.

For more information, see Enable Error Reporting.

PHP Error Reporting Level

If you suspect a problem with PHP, you can also change the PHP error reporting level in your configuration.php file.

SQL Debug Mode

If you suspect a problem with your database, you can enable SQL Debug Mode in the Other tab at Configuration () > System Settings > General Settings. After you enable error reporting, reproduce the problem and then check the logs and module queue again

3. Check for misconfigurations in WHMCS.

In some cases, misconfiguration can cause unwanted actions or unexpected issues. Check the related settings and make sure that they are correct.

The exact settings to check depend on your specific issue and the features it relates to. Often, this will include the following areas of WHMCS:

Configuration () > System Settings > General Settings
Configuration () > System Settings > Automation Settings
Configuration () > System Settings > Products & Services
Configuration () > System Settings > Servers

Check the documentation for each setting as you review it.

4. Ensure that your system, modules, and customizations are up-to-date.

If you suspect that the problem may be due to old files or a recent update:

Refresh any related directories and restore your customizations.
Make certain that you are using a supported version of WHMCS.
Make sure that all of your customizations and third-party modules are up-to-date and work with your current WHMCS version.

Advanced Troubleshooting

Exercise caution when using the steps below. Some methods are only recommended for advanced users.

Customizations and Third-Party Modules

Many issues in WHMCS are due to misconfigured or out-of-date third-party code. Other issues may indicate a bug in your customizations or a third-party module.

Hooks

If WHMCS is not performing actions as you expect, the issue may relate to hooks in third-party code. Check whether hooks are loading, triggering, and running correctly.

For steps, see Troubleshooting Hooks.

You can also disable hooks to test whether the error still happens without them. If the error does not occur, you can then disable and test each hook individually to find the problem.

Modules

To test whether a module is causing the problem, set the permissions for that module’s directory in /modules/addons to 000. If the problem does not occur, the module is part of the issue.

If problems are due to a third-party module, contact that module developer for help.

Cron Failures

If you have problems with automated tasks, you can run the system cron manually to reproduce the issue.

For steps and more information, see Cron Failures.

Last modified: October 11, 2024