WHMCS Troubleshooting: The Diagnostic Flowchart

WHMCS troubleshooting is mostly about knowing where to look. The platform is opinionated about logging — it captures a lot, but the logs are scattered across seven different places, and people waste hours searching the wrong one.

This is the diagnostic flowchart I use, in the order I use it. Top down: cheapest checks first, deepest debugging last.

The mental model — what to check, in order

1. WHMCS Admin → System Health Status. 30 seconds. Catches license, cron, encryption-hash, server-load issues.
2. The logs WHMCS itself writes. Activity, Module, Gateway, API, Email logs.
3. The PHP error log. For white screens, 500 errors, fatal errors.
4. The web server access log. For "is the request even reaching WHMCS?"
5. The MySQL slow-query log. For "everything is slow."
6. Cron output redirected to a file. For automation that silently fails.
7. WHMCS support, escalated with all of the above. Last resort.

I almost never skip a layer. Skipping is what turns a 20-minute fix into a 4-hour rabbit hole.

Symptom: White screen / 500 error

The page returns empty or generic 500. No useful info on screen.

Step 1 — Enable error display temporarily.

Two ways. WHMCS Admin (if accessible): Setup → General Settings → Other → Display Errors → On. Reload. The error appears.

If admin is also broken, edit /path/to/whmcs/configuration.php and add:

$display_errors = true;

Reload. The error appears. Remove this line as soon as you're done — leaking error details in production exposes file paths and configuration.

Step 2 — Read the PHP error log.

Find it: php -i | grep error_log. Typical locations:

• cPanel: /home/USER/public_html/error_log or /usr/local/apache/logs/error_log
• Plesk: /var/log/plesk-php82-fpm/error.log
• Nginx + PHP-FPM: /var/log/php-fpm/error.log

The most recent entries are at the bottom. Look for fatal errors, stack traces, "out of memory", "max execution time exceeded."

Common causes:

• Memory limit. Bump memory_limit in php.ini from 128M to 256M or higher.
• Missing PHP extension. WHMCS needs ionCube Loader and several extensions (curl, openssl, mbstring, mysqli, gd). php -m | sort to list installed; cross-reference WHMCS's requirements.
• Wrong PHP version. WHMCS 8.x requires PHP 7.4+ and 8.x supports specific versions. Don't run "latest" PHP without checking.
• File permission issues on storage/, attachments/, downloads/. Fix with chown -R www-data:www-data /path/to/whmcs/storage + chmod -R 755.

Symptom: Cron not running / automation broken

Invoices aren't generating, reminders aren't sending, services aren't being suspended on time.

Covered in depth in my cron jobs guide. Quick checklist:

1. WHMCS Admin → Utilities → System → System Health Status — what does it show for "Cron Last Run"?
2. SSH in and run cron manually:

   sudo -u www-data /usr/bin/php /path/to/whmcs/crons/cron.php
   

   Watch the output.
3. Check crontab -l -u www-data — is the cron entry actually there with the correct path?
4. Check /path/to/whmcs/storage/logs/automation/ for the most recent log file.

Symptom: Emails not sending

Customers aren't getting welcome emails, invoices, or password resets.

Step 1 — Send a test email from WHMCS.

Utilities → Email Message Log → Send Test Email. Enter your address. Check spam folder. If it arrives, the SMTP path works.

Step 2 — Check the Email Log.

Utilities → Logs → Email Message Log — filter by date. If outgoing emails are being attempted, they appear here. Status column shows "Sent" or an error.

Step 3 — Check SMTP config.

Setup → General Settings → Mail. Verify:

• Mail Type: PHP Mail vs SMTP. SMTP is more reliable.
• SMTP credentials test cleanly (use "Test Connection" if available).
• From / Reply-To addresses are valid.

Common causes:

• SPF/DKIM/DMARC misconfigured. WHMCS sends successfully but Gmail/Outlook silently reject. Check by sending to a Gmail address and using their headers viewer to inspect the SPF/DKIM verdict.
• Mail queue enabled but no queue cron. See cron guide.
• Hosting provider blocks port 25. Common on shared hosting. Switch to SMTP on port 587 with auth.
• SMTP user has no "send as" permission for the From address. Common with Google Workspace.

Symptom: Payments are processed in gateway but invoice stays unpaid

Stripe / PayPal shows the charge succeeded. WHMCS invoice still says unpaid.

The webhook between gateway and WHMCS isn't working.

Step 1 — Check the gateway log.

Utilities → Logs → Gateway Log — search by invoice number or transaction ID. If empty, the callback URL isn't being hit.

Step 2 — Check the gateway's webhook log.

Stripe Dashboard → Developers → Webhooks → your endpoint → recent deliveries. Stripe shows the HTTP response WHMCS returned. Look for non-200 codes.

Step 3 — Test the callback URL directly.

curl -I https://yourwhmcs.com/modules/gateways/callback/stripe_payments.php

You should get a 200 or 405 (Method Not Allowed for GET — the endpoint accepts POST only, which is fine).

Common causes:

• Cloudflare or WAF blocking the gateway's IPs. Whitelist gateway IPs or temporarily relax WAF rules for the callback path.
• Webhook secret mismatch. Gateway signs the payload; WHMCS validates the signature. If signatures don't match, WHMCS returns 400 silently. Re-paste the webhook secret from gateway dashboard into WHMCS gateway config.
• The callback file is missing or has a syntax error. Check /modules/gateways/callback/ exists and the file loads (test by running php -l on it).

Symptom: "Invalid License Key" / License errors

You see a red banner: license invalid, expired, or domain mismatch.

Step 1 — Confirm what your license is registered to.

Log in to members.whmcs.com. Your license shows the registered domain + IP.

Step 2 — Compare to where WHMCS is actually running.

Look at WHMCS Admin → Utilities → System → System Information. If domain or IP differs (you migrated server, changed domains, your hosting provider changed your IP), update the license registration in members area.

Step 3 — Force a license check.

WHMCS caches the license result. Force re-validation: Utilities → System → System Information → Reload License Info.

If you're stuck with no admin access because of the license error, edit configuration.php and remove the cached license: WHMCS will re-check on next request.

Symptom: Database errors, "Connection lost", "Table marked as crashed"

Less common in 2026 but happens on neglected servers.

"Connection lost" or "Too many connections" — MySQL is overloaded. Check SHOW PROCESSLIST. Look for hung queries. Often the cause is a single rogue cron task or a custom hook making heavy queries.

"Table marked as crashed and should be repaired" — MyISAM table corruption. Repair:

mysqlcheck -u root -p --repair --all-databases

Then migrate the affected tables to InnoDB:

ALTER TABLE tblxxxxx ENGINE=InnoDB;

WHMCS supports InnoDB and you should be on it.

"Deadlock found when trying to get lock" — two transactions are trying to update the same rows. WHMCS retries internally; if you see this often, look for custom hooks or modules holding long transactions.

Symptom: WHMCS is slow across the board

Pages take 5+ seconds. Admin and client area both feel sluggish.

Step 1 — Confirm where the slowness is.

Enable WHMCS slow-query logging temporarily: in configuration.php:

$display_query_debug = true;

(Remove after diagnostics — it dumps queries to the output.)

Each page now shows query count + time. If 200+ queries per page → likely an N+1 in a custom module/hook. If 5 queries take 4 seconds → DB or storage.

Step 2 — Database tuning.

Common wins on stock WHMCS:

# my.cnf
innodb_buffer_pool_size = 1G    # for <5GB databases; size to ~70% of RAM otherwise
innodb_flush_log_at_trx_commit = 2  # less safe but much faster, OK for WHMCS
query_cache_type = 0            # disabled — query cache hurts more than helps in modern MySQL

Restart MySQL after changes. Take a backup first.

Step 3 — Identify slow tables.

SELECT table_name, table_rows
FROM information_schema.tables
WHERE table_schema = 'whmcs_db_name'
ORDER BY table_rows DESC LIMIT 10;

Most often huge: tblactivitylog, tblmodulelog, tbltickets. WHMCS can prune these from Utilities → System Cleanup.

Step 4 — Disable heavy modules temporarily.

Some addon modules execute on every page load. Disable them one by one to isolate which is the culprit.

Symptom: Something broke after a WHMCS upgrade

A feature worked before the upgrade and doesn't now.

1. Read the changelog for the version you upgraded to. WHMCS deprecates/changes things between versions; the changelog calls out breaking changes.
2. Check custom modules / hooks for deprecated APIs. WHMCS warns about deprecated function calls in the activity log on first use. Search Utilities → Logs → Activity Log for "deprecated".
3. Theme broken? Check if you edited six directly (you shouldn't have); the upgrade overwrote your changes.
4. Roll back if needed. WHMCS supports downgrade only manually (restore files + restore DB from pre-upgrade backup). This is why you take backups before upgrades.

When to escalate to WHMCS support — and what to send

If you've worked through the layers and can't resolve, open a ticket at members.whmcs.com with:

1. WHMCS version (Setup → General Settings)
2. PHP version (php -v)
3. MySQL/MariaDB version
4. Web server (Apache/nginx/LiteSpeed) + version
5. The exact error message and where it appears (page URL or admin path)
6. What you've already tried
7. Relevant log excerpts (activity log, module log, PHP error log) — paste plain text, not screenshots

This gets you a useful response on first reply. Without it, you'll get the standard "have you tried clearing cache" reply and lose a day.

Common pitfalls

"I turned on Display Errors and now the page works but customers see file paths." Turn it off in production immediately. Use the PHP error log instead.

"I'm searching the activity log but events are missing." Activity log only retains a default 30 days. WHMCS prunes older entries. For longer retention, increase the limit in Setup → General Settings → Other.

"I see encrypted passwords in module log." WHMCS encrypts serverpassword in the DB but decrypts before passing to modules. If you see ciphertext in your log, you're logging the wrong variable. Use the $params array values, never raw DB columns.

"WHMCS is throwing a vague error I can't find on Google." Search configuration.php for cache settings. Many "weird" errors clear after deleting /templates_c/ (Smarty's compiled-template cache).

My take — the troubleshooting habits that pay off

1. Keep a runbook per WHMCS install. Document your specific server paths, PHP binary location, log file locations, cron entries. The first 10 minutes of any incident go to "where do I look?" Save them.
2. Tail logs while you reproduce. Open three terminals: PHP error log, WHMCS activity log, web server access log. Reproduce the issue. The relevant log usually announces itself.
3. Don't disable logging "because it's noisy." Noisy logs are useful logs. Filter, don't silence.
4. Take regular DB backups + know how to restore. The most expensive WHMCS issue I've ever solved was "we lost a week of orders." It wouldn't have been if backups had worked.

Going further

• WHMCS troubleshooting docs
• System Health Status reference
• Activity log documentation

I troubleshoot WHMCS installs for hosting businesses every week — slow admin areas, broken automation, gateway issues, mysterious errors. If you're stuck, send me what you're seeing and I'll diagnose + fix. Quote in 24 hours.