WHMCS Cron Jobs: Command, Frequency, Status and Debugging

What does the WHMCS cron job do?

The WHMCS system cron runs every automated task on a self-hosted install: it generates invoices, captures payments, sends reminders, suspends and terminates overdue services, syncs domains and takes the database backup. Without it, billing is manual. WHMCS Cloud runs the cron for you, so this guide is for self-hosted installs.

Most tasks run once a day. A few run monthly, and one is allowed to run as often as every minute, which is why the cron has to be called often. The System Cron page lists the full set in the order WHMCS runs them. These are the rows that decide how often you call it:

Batch sizes are caps per run: 4,000 active domains need 80 hourly runs of --DomainStatusSync to sync once.

What is the correct WHMCS cron command?

The documented form is the line below, with the path changed to match your install.

*/5 * * * * php -q /home/username/crons/cron.php

Do not type the path from memory. Go to Configuration > System Settings > Automation Settings, click the first status badge and copy the line shown under Cron Command with the copy icon next to it. Where you paste it depends on the server, as Configure the System Cron Job describes:

• cPanel: open Cron Jobs, choose Once Per Five Minutes and paste the command.
• Plesk: open Scheduled Tasks for the domain, enter the path to cron.php as the script path, select a compatible PHP version and set the cron style to */5 * * * *.
• DirectAdmin: open Cron Jobs under Advanced Features, with */5 for Minute and * for the rest. Here the command must include the full path to the PHP binary: the documentation names /usr/bin/php, /usr/bin/home/php and /usr/local/bin/php.
• No control panel: run crontab -e as the account that owns WHMCS and add the line.

That page also lists wget and GET forms, a fallback for hosts with no shell. WHMCS answers HTTP calls to crons/cron.php, and to the legacy admin/cron.php alias, with a 403 until you add the scheduler's IP address to Cron HTTP Access Restriction on the Security tab of General Settings.

A second script, crons/pop.php, is only needed if you import support email by POP3. It also runs every five minutes, and the documentation recommends email piping over it.

WHMCS recommends moving the crons folder above the web root. If you do, set $whmcspath in crons/config.php (renamed from config.php.new), add $crons_dir to configuration.php, and update the cron command.

How often should the WHMCS cron run?

Every five minutes is the recommendation, and once an hour is the documented minimum. A frequent cron does not repeat work, because WHMCS never performs a task more often than that task's own schedule. An hourly cron delays everything that could run every few minutes, such as ticket escalations and the jobs queue. A cron that runs once a day can miss the Time of Day hour, and then the daily tasks do not run.

The Cron Frequency Warnings page adds one step: if the entry is right and the warning stays, check the server's timezone next.

How do you set the hour for WHMCS daily tasks?

Set Time of Day under Scheduling at Configuration > System Settings > Automation Settings. The default is 9:00am local server time.

• The daily tasks start the first time the cron is called during that hour. If the cron is not called at least once inside the hour, they do not run.
• WHMCS takes the current time from PHP when cron.php runs. The timezone configured for WHMCS must match the server's timezone.
• When the daily run is missed, WHMCS sends an email titled WHMCS Daily System Cron Attention Needed. The documented fix is a cron entry of */5 * * * *.
• After you fix the entry, the email can keep arriving. The Cron Time of Day Issues page says further copies may come until the Time of Day hour comes round again, up to 24 hours later. Wait that out before changing anything else.
• Pick the hour deliberately. Everything slow happens inside it: invoicing, payment capture, suspensions, terminations and the database backup.

Where does WHMCS show the cron status?

WHMCS shows it at Utilities > Automation Status, which also opens from the gear icon at the top of the Admin Area. A badge at the top of the page gives the overall state, as explained in Check the Cron Job Status.

Click the badge for a report of recent runs. A failed task shows an x under Status and a Learn more link. After a fix, wait at least five minutes and click Refresh.

The Admin Dashboard also has an Automation Overview widget with seven days of history. The Activity Log at Configuration > System Logs should show entries that begin with Cron Job every day, ending with Cron Job: Completed. Suspensions and terminations that fail are retried daily and listed at Utilities > Module Queue.

Which cron.php options are worth knowing?

Five arguments and a few flags exist, and the documentation says most installs need none of them. The table has the main ones.

Passing arguments needs PHP's register_argc_argv directive enabled. The documented use for skip and do is to give one task its own schedule. This is the documentation's own example, keeping escalations to office hours and suspensions to weekday mornings:

*/5 * * * * php -q /path/to/cron.php skip --TicketEscalations --AutoSuspensions
0 9,10,11,12,13,14,15,16 * * 1-5 php -q /path/to/cron.php do --TicketEscalations
0 9 * * 1-5 php -q /path/to/cron.php do --AutoSuspensions

Write both entries at once: a task you skip and forget to schedule separately never runs.

Why is the WHMCS cron job not working?

Usually because the server is not calling cron.php, is calling it at the wrong path, or is running it with a different PHP from the website.

In words: a green badge means automation is healthy. If not, no Cron Job entries in the Activity Log means the cron entry is wrong or missing; entries plus a failing manual all -F -vvv run means fix the error it prints. If the manual run is clean, daily tasks that miss the Time of Day hour point at Time of Day or the timezone, and daily tasks that make it point at an intermittent failure.

The PHP version mismatch row is worth checking on any server with several PHP versions. Compare Loaded Configuration File at Utilities > System > PHP Info with the output of php -i | grep "Loaded Configuration File", run as the account that owns WHMCS and not as root. Both must point to the same PHP version. The warning clears only after the next daily run.

How do you debug the WHMCS cron?

Run it by hand with full output, following the Cron Failures page.

1. Enable Display Errors in the Other tab at Configuration > System Settings > General Settings.
2. Copy the Cron Command from Utilities > Automation Status.
3. On the server, run php -i | grep display_errors to confirm errors will be shown. When it is on, the documented output is display_errors => STDOUT => STDOUT.
4. Run the command with all -F -vvv added to the end.
5. Read the output. A clean run ends with [OK] Completed.

php -q /home/example/public_html/whmcs/crons/cron.php all -F -vvv

Because -F forces the daily tasks again, the documentation says not to do this more than once in 24 hours. A clean run moves the problem from the install to how the server invokes it.

For a cron that fails only sometimes, follow the Intermittent Cron Failures page: append -vvv >> crondebug.txt to the scheduled command, wait until the Time of Day hour has passed, then open crondebug.txt in the account's root directory. It holds one block per invocation, and the documented way to find the daily run is a block with 24 or more tasks queued. A good block ends with [OK] Completed; a bad one stops partway on an [ERROR] line. The worked example there is a provisioning module that could not resolve a hostname, which is the usual shape: not the cron, but one task reaching outside the server.