WHMCS Troubleshooting: Common Issues and Solutions

When WHMCS breaks, your billing operations stop. Quick diagnosis and resolution is critical. This guide covers the most common WHMCS problems I encounter while helping hosting companies, with step-by-step solutions for each. Bookmark this as your first reference when issues arise.

Cron Job Not Running

The most frequent and impactful issue. If cron stops, invoices don't generate, reminders don't send, and automation breaks down completely. You might notice this days later when customers complain about missing invoices or services not suspending.

Symptoms

Automation Status in admin shows last run was many hours or days ago p, no new invoices are being generated, payment reminders aren't sending, and services aren't suspending for non-payment.

Diagnosis Steps

First, verify the cron entry exists and is syntactically correct. Check your crontab with the command crontab -l and look for the WHMCS cron entry. It should look something like */5 * * * * php -q /path/to/whmcs/crons/cron.php.

Next, run the cron manually to check for errors using the command php /path/to/whmcs/crons/cron.php. Watch for PHP errors, permission denied messages, or timeout issues that would indicate problems.

Common Solutions

Check the PHP path matches your server configuration. Use which php to find the correct path. Verify file permissions allow execution by the cron user. Check if IonCube loader is installed for command-line PHP since the cron won't run without it. Look for PHP memory limits or timeout issues in error logs.

Payment Gateway Errors

Customers unable to pay means lost revenue. Payment issues range from complete gateway failures to specific transaction rejections.

Symptoms

Checkout throws errors during payment, gateway returns unexpected responses, specific payment methods fail while others work, and customers report declined transactions despite valid cards.

Diagnosis Steps

Check System → Activity Log for detailed error messages related to payments. Review Module Debug Log for API communication details. Test with a small transaction on a test account if possible. Check gateway status pages for provider-side outages.

Common Solutions

Verify API credentials haven't expired or been rotated. Check if gateway API endpoints have changed since providers occasionally update URLs. Ensure your server can reach the gateway through firewall rules. Verify SSL certificate for WHMCS is valid since gateways often reject callbacks to invalid SSL domains. Update the gateway module to the latest version compatible with your WHMCS version.

Provisioning Failures

Customers pay but don't get their service. This creates urgent support tickets and unhappy customers.

Symptoms

Orders remain pending after payment, welcome emails don't send, hosting accounts aren't created on the server, and error messages appear in Module Queue.

Diagnosis Steps

Go to Utilities → Module Queue to see failed provisioning attempts with error details. Check Module Debug Log for API communication with the server. Test server connection in Setup → Servers using the Test Connection button.

Common Solutions

Verify server credentials haven't changed since password changes break API access. Check if the server IP has changed since DNS updates might be needed. Ensure the server has available resources for account creation like disk space and account limits. Verify the product module settings match server configuration. Check network connectivity between WHMCS and the server, especially if they're on different networks.

Email Delivery Problems

Customers not receiving emails creates confusion and support overhead. Invoices, welcome emails, and notifications all depend on email working.

Symptoms

Customers don't receive expected emails, emails appear in Mail Queue but don't deliver, bounce messages appear in Email Log, and emails go to spam folders.

Diagnosis Steps

Check Utilities → Mail Queue for stuck messages. Review Mail Log for delivery status and errors. Test SMTP configuration with Setup → Mail → Test Email.

Common Solutions

Configure proper SMTP instead of PHP mail for reliable delivery. Verify SMTP credentials if using external mail service. Check SPF, DKIM, and DMARC records for your sending domain. Ensure sending domain matches your WHMCS system domain. Review queued message content for spam triggers and avoid excessive links or promotional language.

Database Connection Errors

When WHMCS can't reach the database, everything breaks. These are urgent, high-impact issues.

Symptoms

White page or connection refused errors, specific pages fail while others work indicating query problems, slow page loads suggesting database performance issues, and error messages mentioning MySQL or database.

Diagnosis Steps

Check if MySQL service is running with systemctl status mysql. Try connecting manually using command line MySQL with credentials from configuration.php. Review MySQL error logs for specific failures.

Common Solutions

Restart MySQL service if it crashed using systemctl restart mysql. Check disk space since MySQL stops working when disk is full. Verify database user permissions haven't been revoked. If the database is on a separate server, verify network connectivity between WHMCS and the database server. Increase MySQL connection limits if hitting max_connections.

SSL and HTTPS Issues

SSL problems cause browser warnings that frighten customers away from your billing system.

Symptoms

Browser shows not secure warnings, mixed content warnings on pages, payment gateways reject callbacks, and certificate expired errors appear.

Diagnosis Steps

Check certificate expiration date using browser developer tools. Use SSL testing tools like SSL Labs to check configuration. Look for mixed content in browser console.

Common Solutions

Renew expired certificates immediately. Fix mixed content by updating hardcoded HTTP URLs to HTTPS. Ensure WHMCS System URL setting in General Settings uses HTTPS. Update htaccess to force HTTPS redirect.

White Screen of Death

A blank white page with no error message. Usually indicates a fatal PHP error.

Symptoms

Blank white page rather than expected content, sometimes affects only client area or only admin, and no error message is displayed.

Diagnosis Steps

Enable PHP error display temporarily to see the actual error. Check PHP error logs at server level. Check WHMCS error logs directory.

Common Solutions

Increase PHP memory limit since common cause is exhausted memory. Check for corrupted files after update so you may need to reupload from fresh download. Disable recently installed addons by renaming their directories. Verify PHP version compatibility with your WHMCS version.

Login Problems

Users unable to log in creates urgent support situations and blocks business operations.

Symptoms

Login form rejects valid credentials, session immediately logs out, two-factor authentication fails, and admin access locked out.

Diagnosis Steps

Check if cookies are being set by inspecting browser storage. Verify session storage has write permissions. Review activity log for login attempts and failures.

Common Solutions

Clear browser cookies and cache. Check PHP session configuration for proper functioning. Verify session storage directory permissions. If locked out of admin, disable 2FA via database query. Reset passwords through direct database update if necessary.

Performance Problems

Slow WHMCS frustrates staff and customers, reducing productivity and satisfaction.

Symptoms

Pages take many seconds to load, timeouts during checkout, slow admin area especially reports, and cron takes hours to complete.

Diagnosis Steps

Check server resources including CPU, RAM, and disk I/O. Enable MySQL slow query logging to find problematic queries. Use browser developer tools to identify slow requests.

Common Solutions

Optimize database tables through WHMCS Utilities. Add database indexes if missing. Increase PHP memory and execution limits. Enable OPcache for PHP acceleration. Consider Redis for session storage. Reduce activity log retention in General Settings. Move database to SSD storage if not already using SSD.

Getting Help

When self-troubleshooting fails, escalate appropriately. Check WHMCS Community Forums for similar issues. Open official WHMCS support ticket with detailed error information. For urgent issues, consider hiring a WHMCS expert for immediate resolution.

Conclusion

Most WHMCS issues fall into predictable categories with known solutions. Systematic diagnosis starting with logs and error messages usually reveals the cause. Keep this guide handy for quick reference when problems arise. For complex or recurring issues, consider a professional audit to identify and fix root causes rather than repeatedly addressing symptoms.