WHMCS Cron Jobs: Setup, Troubleshooting, and Monitoring

Half the WHMCS support tickets I see come down to "the cron isn't running properly." Invoices that didn't generate. Reminders that didn't send. Services that didn't provision. The fix is almost always the same three things, but nobody documents them clearly.

This is the field guide. I've set up the WHMCS cron on dozens of servers across cPanel, Plesk, DirectAdmin, and bare-metal Linux. The pattern below works on all of them.

What the WHMCS cron actually does

WHMCS isn't a real-time system. Almost every "scheduled" thing — invoice generation, due-date checking, overdue reminders, service termination, email queue processing — happens because the cron runs and executes those tasks. No cron, no automation. Your WHMCS becomes a manual billing tool.

The cron runs a single PHP script: /path/to/whmcs/crons/cron.php. This script orchestrates roughly 30 sub-tasks, each with its own schedule. WHMCS handles which tasks run today vs. weekly vs. hourly — you just need to make sure cron.php runs every 5 minutes.

Step 1 — Set the cron line correctly

The single line that should be in your crontab:

*/5 * * * * /usr/bin/php -q /path/to/whmcs/crons/cron.php >/dev/null 2>&1

Critical details, in order of frequency-with-which-people-get-them-wrong:

1. Every 5 minutes (*/5 * * * *), not hourly or daily. WHMCS expects the cron to fire frequently. Many tasks self-limit (daily ones won't repeat) but the cron must opportunity to run frequently or async tasks pile up.
2. Full path to PHP binary. php alone often resolves to the wrong PHP version in cron's stripped-down environment. On cPanel: /usr/local/bin/ea-php82 or wherever your server's WHMCS-compatible PHP lives.
3. Full path to cron.php. Cron has no concept of "the current directory."
4. Redirect output. >/dev/null 2>&1 sends stdout and stderr to nowhere. Without this, cron emails you every 5 minutes. With it, you discard valuable error info — so route to a log file instead for debugging (see below).

Step 2 — Where to put the cron entry

The right place depends on your environment:

cPanel server

Log in to cPanel as the user that owns the WHMCS files. Cron Jobs → Add New Cron Job. Use the cPanel UI rather than editing /var/spool/cron/ directly — keeps it auditable in the cPanel UI.

Bare-metal Linux

Edit the crontab of the user that owns the WHMCS files (typically www-data on Debian/Ubuntu, nginx/apache on RHEL/CentOS, or a dedicated whmcs user):

crontab -u www-data -e

Never run the WHMCS cron as root. Any file the cron creates will be owned by root and unwritable to the web server later. This causes spectacular debugging sessions.

Plesk / DirectAdmin / CloudPanel

All have a cron UI in the panel. Use it; same constraints apply.

Step 3 — Verify it actually runs

Three reliable checks:

1. WHMCS Admin → Utilities → System → System Health Status. It shows the last time the cron successfully ran. If "Cron Last Run" is hours ago, cron isn't running.

2. Watch the cron log. WHMCS writes to /path/to/whmcs/storage/logs/automation/. Tail the most recent file:

tail -f /path/to/whmcs/storage/logs/automation/2026-05-25.log

You should see entries every 5 minutes.

3. Run it manually and confirm. SSH in as the cron user and run:

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

Watch the output. Success looks like a series of task starts and completions. Errors include their text — usually database connection issues, PHP version problems, or memory limits.

Recommended schedule split (for larger installs)

WHMCS Automation Settings (Setup → Automation Settings) lets you split which tasks run when. On a busy install with thousands of services, running everything in a single 5-minute window can spike database load. The pattern I use:

Set these in WHMCS Automation Settings, not in cron itself. WHMCS handles the timing internally.

Step 4 — Debugging a slow or hanging cron

A common pain: the 5-minute cron now takes 15 minutes to complete, so two instances run simultaneously and step on each other. Symptoms:

• Duplicate invoices for the same client.
• Provisioning attempts that race and create two accounts.
• The cron log shows partial completions with no errors.

Fixes:

1. Add a lock with flock:

*/5 * * * * /usr/bin/flock -n /tmp/whmcs.cron.lock /usr/bin/php -q /path/to/whmcs/crons/cron.php >> /var/log/whmcs-cron.log 2>&1

flock -n means "if the lock is already held, exit immediately without running." A backlog can't form.

2. Investigate why it's slow. Enable WHMCS slow-task logging in Setup → Automation → Show Detailed Logs. Look for the task that takes the most time — usually email sending against a misconfigured SMTP, or a module that's making slow external API calls.

3. Split the cron into two: the main cron runs frequent tasks; a separate cron line runs heavy tasks daily during off-peak. WHMCS has built-in support for this in Automation Settings.

The email queue — a special case

WHMCS optionally queues outgoing emails (Setup → General Settings → Mail → Enable Mail Queue) so that bulk operations don't block on slow SMTP servers. If you enable this, you need a separate cron line for the queue:

*/5 * * * * /usr/bin/php -q /path/to/whmcs/crons/cron.php sendqueuedemails >/dev/null 2>&1

Forgetting this is a classic "no emails are sending but no errors" mystery.

Step 5 — Monitor cron health

You should be alerted within 30 minutes if the cron stops running. Three approaches:

1. Healthchecks.io / Dead Man's Snitch — change the cron line to ping a URL on success:

   */5 * * * * /usr/bin/php -q /path/to/whmcs/crons/cron.php && /usr/bin/curl -fsS -m 10 --retry 5 https://hc-ping.com/YOUR-UUID >/dev/null
   

   Healthchecks alerts you if it doesn't ping every N minutes.
2. Polling check inside your monitoring stack. Query tblconfiguration for NextCronInvocation and alert if more than 15 minutes stale.
3. WHMCS built-in "Cron Stopped" warning. WHMCS shows a red banner in admin if the cron hasn't run recently. Better than nothing but useless if no human logs in to see it.

Common pitfalls

"Cron runs but invoices aren't generating." Wrong PHP version in cron environment. The WHMCS file cron.php bootstraps but parts of WHMCS need a specific PHP version, and silently misbehave on others. Use php --version with the exact path you're using in cron to confirm.

"Cron fails with 'php: command not found'." Cron's PATH is minimal. Use the full path: /usr/bin/php, /opt/cpanel/ea-php82/root/usr/bin/php, etc.

"Cron generates duplicate invoices." Two cron jobs are configured (often after a migration left the old one in place). Or the lock fix above is missing and runs overlap. List crons with crontab -l -u www-data.

"Cron runs but never updates 'Cron Last Run' in admin." File permission issue. The cron user can't write to /path/to/whmcs/storage/logs/. Check ownership: ls -la /path/to/whmcs/storage/ and fix with chown -R www-data:www-data (or your specific user).

"Cron started failing after a WHMCS upgrade." The upgrade may have changed the recommended cron line. Check the upgrade notes — recent WHMCS versions prefer crons/cron.php over the old cron.php. Update the cron line.

My take — the cron checklist on every server I touch

1. Cron runs as the same user that owns the WHMCS files.
2. Cron line uses absolute paths to PHP and cron.php.
3. Email queue cron (if email queue is enabled) is separate.
4. flock in place to prevent overlap.
5. Healthchecks.io ping on success.
6. Cron user has write access to storage/logs/.
7. WHMCS slow-task logging enabled so I can see if any task is creeping up over time.

This takes 15 minutes to set up once. It removes an entire category of WHMCS support tickets forever.

Going further

• WHMCS cron documentation
• Automation Settings reference
• Healthchecks.io (the easiest cron monitor I've used)

I troubleshoot WHMCS cron / automation issues weekly for hosting clients. If yours is misbehaving and you can't pin down why, send me the details and I'll diagnose + fix it. Quote in 24 hours.