How to debug WHMCS cron job activity

[Remitur]

I've recently had to investigate one of those slightly annoying WHMCS problems: the cron job appears to be running correctly, but some executions never actually finish.

This can be surprisingly easy to miss.

Having cron.php started every 5 minutes only tells us that cron is starting it every 5 minutes. It doesn't tell us whether the previous execution actually completed. If an automation task hangs — because of an external API, a registrar/module, a network problem, a database issue, custom code, etc. — you may eventually end up with several overlapping cron.php processes without immediately noticing what is going on.

I put together a debugging approach that gives visibility into three different levels:

• whether the PHP cron process actually starts and terminates;

• whether the WHMCS automation cycle enters and exits normally;

• which individual WHMCS automation task starts but never returns (or simply takes an unusually long time).

The basic idea is to use the PreCronJob / AfterCronJob and PreAutomationTask / PostAutomationTask hooks, combined with a simple external shell wrapper and a check for overlapping processes.

Instead of just knowing:

"The WHMCS cron seems to get stuck sometimes."

you can hopefully get to something much more useful, such as:

cron.php started
DomainSync started
another cron.php process started
another cron.php process started
DomainSync never returned

At that point, at least you know where to start looking.

I've written up the complete procedure, including the hooks, shell script, logging examples and some additional notes here:

https://eurossl.eu/knowledgebase/whmcs-cron-job-stuck-debugging/

I'm posting this because I'd still like to contribute useful technical information back to the WHMCS community.

However, after fighting over the years with the community's occasionally ("creative" code editor, formatting issues, disappearing posts and similar adventures), I've decided to keep the full article and code somewhere I can actually maintain them. 🙂

Hopefully this will save someone a few hours of debugging.

 

[joeroot6543]

On 9/6/2026 at 2:04 PM, Remitur said:

I've recently had to investigate one of those slightly annoying WHMCS problems: the cron job appears to be running correctly, but some executions never actually finish.

This can be surprisingly easy to miss.

Having cron.php started every 5 minutes only tells us that cron is starting it every 5 minutes. It doesn't tell us whether the previous execution actually completed. If an automation task hangs — because of an external API, a registrar/module, a network problem, a database issue, custom code, etc. — you may eventually end up with several overlapping cron.php processes without immediately noticing what is going on.

I put together a debugging approach that gives visibility into three different levels:

• whether the PHP cron process actually starts and terminates;

• whether the WHMCS automation cycle enters and exits normally;

• which individual WHMCS automation task starts but never returns (or simply takes an unusually long time).

The basic idea is to use the PreCronJob / AfterCronJob and PreAutomationTask / PostAutomationTask hooks, combined with a simple external shell wrapper and a check for overlapping processes.

Instead of just knowing:

"The WHMCS cron seems to get stuck sometimes."

you can hopefully get to something much more useful, such as:

cron.php started
DomainSync started
another cron.php process started
another cron.php process started
DomainSync never returned

At that point, at least you know where to start looking.

I've written up the complete procedure, including the hooks, shell script, logging examples and some additional notes here:

https://eurossl.eu/knowledgebase/whmcs-cron-job-stuck-debugging/

I'm posting this because I'd still like to contribute useful technical information back to the WHMCS community.

However, after fighting over the years with the community's occasionally ("creative" code editor, formatting issues, disappearing posts and similar adventures), I've decided to keep the full article and code somewhere I can actually maintain them. 🙂

Hopefully this will save someone a few hours of debugging.

 

I also have the same question, because I’ve run into situations where a WHMCS cron job appears to be running normally from the outside, but something inside the automation process seems to take much longer than expected or never properly finishes. What makes this particularly difficult to troubleshoot is that simply seeing the cron command execute every few minutes doesn’t necessarily tell you what happened during the previous run. If one process is still active when the next scheduled execution begins, it seems very easy to end up with multiple cron processes running at the same time without realizing that the original problem is actually a task that is waiting indefinitely somewhere. I’ve generally found these kinds of issues difficult to diagnose when all you have is a basic cron log showing that the command was launched, because that doesn’t really tell you which part of the WHMCS automation cycle was reached before things stopped progressing. Being able to distinguish between the PHP process starting, the overall automation cycle starting and finishing, and an individual automation task starting but never returning sounds like a much more useful way of narrowing down the problem. I’m especially interested in the idea of logging the individual task names because otherwise it can be difficult to tell whether the delay is related to WHMCS itself, a particular module, an external service, or some custom code running during automation.