Craft queue stuck? Why form emails stop sending, and how to fix it for good

What the Craft queue does

Craft hands slow work to a background to-do list called the queue, so that saving a page or submitting a form doesn’t keep anyone waiting. Craft itself uses it for things like updating search indexes, resaving entries in bulk, and generating image transforms. Plugins use it too. Commerce sends order emails through it, and form plugins and caching plugins often lean on it for notifications and cache clearing. (Check your own plugins’ settings; it varies.)

When the queue moves, you never think about it. When it stops, those jobs just sit there waiting.

Signs your queue is stuck

• Form notification emails arrive late, in a burst, or not at all.
• Edits don’t show up on the live site until someone clears caches by hand.
• Image thumbnails or resized images are missing.
• The control panel sidebar shows a job that never finishes, or a failed job.
• Things only seem to “catch up” after someone logs into the control panel.

That last one is the biggest clue, and it points straight at the cause.

Why it happens

Out of the box, Craft runs the queue over the web. At the end of a page request, if jobs are waiting, Craft adds a small script to the page that kicks off the queue in the background. Control panel pages do something similar. This is controlled by a setting called runQueueAutomatically, which is on by default.

That works fine on a busy site with editors in the control panel every day. On a quieter site, it has gaps:

• No visits, no queue. If nobody loads a page, nothing triggers the queue. Craft also skips this for Ajax requests and non-HTML responses, so a form that submits over Ajax may not kick it off.
• Nobody set up a proper runner. Sometimes a developer turned off runQueueAutomatically on purpose and meant to add a cron job or background worker, and never did. Then the queue doesn’t run at all.

Craft’s own queue docs say that if your site relies on the queue for time-sensitive work, like sending emails, you should run it from the command line instead.

How to check the Craft queue backlog

In the control panel: go to Utilities → Queue Manager. (You need admin rights or the Queue Manager permission.) You’ll see waiting jobs, anything running, and failed jobs. Click a failed job’s description to see what went wrong.

For developers, over SSH: from your project root, this shows the queue’s status:

php craft queue/info

A long list of waiting jobs, or jobs that sit as “reserved” for ages, means the queue isn’t keeping up.

The lasting fix: run the Craft queue from the server

There are two good options.

Option 1: a cron job

This runs the queue on a schedule until it’s empty. Craft’s docs give this example for every five minutes:

*/5 * * * * /usr/bin/env php /var/www/craft queue/run

Use the absolute path to your project’s craft file. Cron doesn’t start in your project folder.

Option 2: a background worker (daemon)

This keeps a process running that picks up new jobs as soon as they arrive, which is better when form emails need to go out right away. Your server’s process manager (usually systemd or supervisor) runs this command and restarts it if it fails:

php craft queue/listen --verbose

Craft’s queue docs include full systemd and supervisor examples. Two things from those docs worth knowing: don’t run the queue as root, and restart the worker after each deploy so it picks up code changes.

Then turn off the web runner

Once a real runner is in place, set runQueueAutomatically to false in config/general.php, or with this environment variable:

CRAFT_RUN_QUEUE_AUTOMATICALLY=false

Craft’s docs specifically say to turn it off while you test a daemon. If you leave it on, the queue might look healthy only because page visits are still running it.

Get warned before the queue backs up

A queue runner keeps jobs moving, but it’s worth knowing when something stalls anyway. We see this so often on sites we take over that we built a plugin for it.

• Watchtower watches Craft’s queue and emails you when jobs start piling up past the limits you set.
• It runs from a cron job, and it can also ping Oh Dear if you use it to monitor scheduled tasks.
• It works on Craft 3, 4, and 5.

composer require siebird/craft-watchtower -w && php craft plugin/install watchtower

Next, set your thresholds and notification email under Settings → Watchtower. Then add a cron job to run the check, for example every hour (use your own project path):

0 * * * * /usr/bin/env php /var/www/craft watchtower/monitor

Clearing stuck and failed jobs

Once a runner is going, waiting jobs will work through on their own. For failed jobs, you can retry them from the Queue Manager, or from the command line:

# Retry one failed job by its ID
php craft queue/retry 123

# Retry every failed job
php craft queue/retry all

To remove jobs instead, use queue/release. Be careful here: releasing takes a job out of the queue, so that work won’t happen. Release only jobs you’re sure you don’t need.

php craft queue/release 123

If form emails still don’t arrive once the queue is clear, the queue may not be your problem. Test the mail settings themselves:

php craft mailer/test --to=you@example.com

When a stuck queue means a bigger problem

Sometimes it really is just a missing cron job. But on the sites we take over, a stalled queue is often the first thing we spot, not the only thing. If the queue was never set up, it’s worth checking whether tested backups, update routines or monitoring are in place too. Jobs that fail over and over can also point at an out-of-date plugin or a server running low on memory.

So if you find a backlog, treat it as a reason to look at the whole site, not just the queue.

Need a hand?

If your queue has been stuck for a while, or you’ve recently taken over responsibility for a Craft site and aren’t sure what else is waiting under the hood, we can help. We can take over your Craft site, working alongside your current team if you’d like: we audit it, fix what’s broken, and give you a plain-language list of the rest.