WHMCS troubleshooting works best as a fixed order of checks: System Health first, then the cron status, then the log that matches the symptom, then the Module Queue, and only then error reporting. This diagnostic flowchart gives that order, the current menu path for every log and a table that maps each common symptom to its likely cause.
I checked the menu paths and setting names below against the WHMCS 9.0 documentation on 10 October 2026. The WHMCS 8.13 documentation shows the same paths.
In what order should you troubleshoot WHMCS?
Work from the cheapest check to the most intrusive one, and stop at the first step that shows an error. This is the flowchart as a list.
- Write down the symptom. Note the page, the action, the time and the exact error text.
- Open Configuration > System Health. Read every item marked Warning or Needing Attention.
- Check the cron. Open Utilities > Automation Status and read the badge.
- Read the log that matches the symptom. The table in the next section says which one.
- Open Utilities > Module Queue if a server, registrar or other module is involved.
- Enable error reporting, repeat the action, read the logs again, then switch it off.
- Suspect settings and custom code. Review the related settings, then test without hooks and third-party modules.
Steps one to five only read what WHMCS has already recorded. The WHMCS Start Troubleshooting page follows the same idea: logs and queue first, error reporting second, configuration third.
Where does WHMCS keep its logs?
Most WHMCS logs are in the admin area at Configuration > System Logs, and the Gateway Log is under Billing. The Logs in WHMCS documentation lists them.
| Log | Menu path | What it records |
|---|---|---|
| Activity Log | Configuration > System Logs | System events, client and user actions and cron runs. PHP errors too, when Log Errors is on. |
| Admin Log | Configuration > System Logs | Admin logins and logouts with IP addresses. |
| Email Message Log | Configuration > System Logs | Emails sent to clients and users, except password reset and email verification messages. |
| Module Log | Configuration > System Logs | What WHMCS sent to a server, registrar or gateway API and what came back. Only while Module Logging is On. |
| Gateway Log | Billing > Gateway Log | Attempted and completed gateway transactions and payment returns. |
| Ticket Mail Import Log | Configuration > System Logs | Ticket emails that were piped or imported. |
| Module Queue | Utilities > Module Queue | Failed module actions, each with a Retry button. |
The Module Log records nothing until you switch it on. Set Module Logging to On, repeat the action, refresh the log and set it back to Off. Your admin role needs the View Module Debug Log permission.
Where does WHMCS write its log files (storage/logs)?
WHMCS writes the logs above to its database, not to files, and it sends PHP errors to your server's error log. The documentation calls that second place the System Environment Log. It is usually the Apache error log, its location is set by the server and not by WHMCS, and WHMCS tries to write errors and uncaught exceptions there even when Log Errors is off. That makes it the place to look when the admin area will not load.
People also search for a storage/logs folder in WHMCS. The official logging page does not list one, and I could not confirm in the documentation what WHMCS writes there, so I do not send you to it. Ask your host where the PHP error log for your account is.
How do you turn on WHMCS error reporting safely?
Tick Display Errors on the Other tab at Configuration > System Settings > General Settings, repeat the action, read the error and untick it straight away. The same tab has three quieter switches, described in the Enable Error Reporting documentation and the settings reference.
- Display Errors prints error detail on the page for anyone who hits the error, customers included.
- Log Errors writes PHP errors to the Activity Log and shows nothing on public pages. I use this one on a live site.
- SQL Debug Mode logs database errors. WHMCS says to enable it only when its support team asks.
- Hooks Debug Mode logs
Hook File LoadedandCalled Hook Pointentries, which show whether a hook loads and fires.
If you cannot log in to the admin area, add $display_errors = true; to configuration.php just before the closing PHP tag, and remove the line when you finish. For mail faults, the Mail tab has a Debugging option for your mail provider.
How do you check whether the WHMCS cron is running?
Open Utilities > Automation Status and read the badge at the top.
- Green, Ok. The cron was invoked in the last 120 minutes and the daily tasks succeeded in the last 24 hours.
- Yellow, Warning. The cron has worked before but has not been invoked in the last 120 minutes.
- Red, Error. The cron has never been invoked, or the daily tasks have not succeeded in the last 24 hours.
Click the badge for the Cron Status report, where a failed task shows an x. The Activity Log should also show entries beginning Cron Job every day, ending with Cron Job: Completed. To see the failure itself, the Cron Failures documentation says to enable Display Errors, copy the cron command from that report and run it on the command line with three extras:
php -q /home/example/public_html/whmcs/crons/cron.php all -F -vvvThe -F option forces every task to run, including daily tasks that already ran, so WHMCS says not to do this more than once in 24 hours.
Which WHMCS symptom points to which cause?
The table maps ten common symptoms to the place to look first and the usual cause.
| Symptom | Where to look first | Likely cause |
|---|---|---|
| Blank or half-drawn page | Error reporting, then the server error log | A fatal PHP error, missing files, an ionCube Loader problem, or an incompatible hook or addon. |
An Oops! Something went wrong page | Error reporting, then repeat the action | After a PHP upgrade: a missing PHP extension or custom code that uses removed functions. |
| Client area blank, admin area fine | The template setting and the templates_c folder | The template folder is missing, or templates_c has a wrong path or is not writeable. |
| Invoices, reminders or suspensions did not run | Utilities > Automation Status | The cron is not being invoked, or a daily task is failing. |
| Account not created, or a suspension failed | Utilities > Module Queue, then the Module Log | The module or the remote server returned an error. |
| Emails not arriving | Email Message Log, then Debugging on the Mail tab | An SMTP login or connection failure, a hook that aborts the send, Disable Email Sending left on, or a client who opted out. |
| Paid at the gateway, invoice still unpaid | Billing > Gateway Log | A return logged as Invalid or Error, for example a wrong invoice ID or amount. |
| Card capture failed with no Gateway Log entry | Pay Methods on the client's Summary tab | The client has no card on file. |
License Invalid at admin login | The $license line in configuration.php | A wrong key, or an install that was moved without reissuing the license. |
An error occurred while communicating with the server | WHMCS System URL on the General tab | The address in your browser does not match the System URL, or a PHP error. |
If the license row is yours after a server move, my guide on how to migrate WHMCS covers the reissue.
How do you find out whether custom code is the cause?
Switch the custom code off and see whether the fault goes away. WHMCS documents a way to do it for each kind.
- Hooks. Add
$disable_hook_loading = true;toconfiguration.php, test, and remove it. WHMCS needs hooks for full function, so do this only while you test. My WHMCS hooks guide explains how hook files load. - Addon modules. Set the permissions of the module's directory in
/modules/addonsto 000. If the fault stops, that module is part of it. - Stray output. When every page is blank, look for spaces or line breaks outside the PHP tags in custom files under
/includes/hooks/and/modules/.
A Module Command Error in the Module Log comes from the module, not from WHMCS. For an encoded third-party module, the vendor is the only one who can change the code.
What are the risks of debugging WHMCS on a live site?
The main risks are showing error detail to customers, running billing tasks twice and filling the database with debug entries.
- Display Errors shows file paths and error text to every visitor who hits the error. System Health flags it while it is on.
- A forced cron run repeats the daily tasks.
- Log Errors, SQL Debug Mode and Hooks Debug Mode can create a large number of Activity Log entries. Utilities > System Cleanup empties logs.
- Disabling hooks or a module switches off whatever it did for your clients while you test.
Take a database backup before you change anything. If clients must stay out while you work, Maintenance Mode on the General tab closes the client area and order form, while the admin area, the API and hooks keep working. I do not edit files that WHMCS ships, because an update can replace them.
When should you contact WHMCS support, and what should you send?
Contact WHMCS support when the steps above point at WHMCS itself and not at your server, your settings or third-party code. Send the exact steps that reproduce the fault, the full error text, what you already tried and the matching log entries. For a cron fault, WHMCS asks for the full output of the command above.
If you would like a second pair of eyes first, I take single faults under hourly WHMCS developer work and ongoing care under WHMCS support and maintenance.
Last reviewed 10 October 2026. Disclosure: I am a freelance WHMCS developer and I sell WHMCS troubleshooting and maintenance as a service, so I am not neutral. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.
