Laravel
Laravel queue jobs not processing? A step-by-step diagnosis
Trace stalled Laravel jobs through dispatch, queue connection, worker selection, failures and deployment configuration without blindly retrying production work.
An application says an export has started, but the file never appears. The queue table contains records, or the dashboard shows pending work. Before adding more workers, trace one known job from dispatch to completion.
The important question is not just “is a worker running?” It is “is the intended worker consuming the intended queue with the intended configuration?”
1. Confirm the job was queued
Check whether the task implements the queue contract and how it is dispatched. A synchronous execution path will not behave like background work, even if the application has queue infrastructure elsewhere.
Use a harmless diagnostic job in a development or staging environment. Give it a reference you can find in logs. Avoid testing with real payment actions or repeated customer notifications.
Read the actual runtime configuration, not only the .env file. A cached configuration or a different process environment can explain why web requests and workers use different connections.
2. Match the connection and queue name
A worker consuming default will not automatically process a job sent only to exports. The connection selects the backend; the queue name selects a work stream within it.
For example, this command consumes the exports queue on a configured Redis connection:
php artisan queue:work redis --queue=exports --once -v
Run it in a controlled environment with a test job. It performs work, not just inspection. Replace the connection and queue with your application’s actual values.
Laravel’s queue documentation covers worker configuration and queue selection. A local command succeeding does not prove that the production process manager uses the same settings.
3. Check worker lifecycle and deployment
Look at process-manager status and worker output. A worker may have exited, be repeatedly restarting or be running from an old release directory.
Long-running workers need a deliberate reload strategy when deploying new code. Use the lifecycle procedure appropriate to your setup, whether that is a process manager, a managed platform or Horizon. Confirm that the replacement process starts and actually consumes a test job.
A restart signal without a mechanism to bring workers back can leave the queue idle. Document both sides of the process: how old workers stop and how new workers start.
4. Distinguish waiting from failure
A pending job may be delayed intentionally. It may also be behind slower jobs, subject to a lock, constrained by rate limiting or waiting for capacity. Inspect its timing and middleware before assuming it is broken.
For failed work, inspect the configured failure storage and relevant exception:
php artisan queue:failed
A useful incident note records the job reference, connection, queue, exception and last observed progress. Do not expose full payloads if they contain private data.
| Symptom | Next check |
|---|---|
| Nothing leaves the queue | Worker health, connection and queue selection |
| One job fails repeatedly | Exception, input data and downstream service |
| Jobs succeed locally only | Runtime configuration and deployment differences |
| The same effect happens twice | Timeout, visibility/retry timing and idempotency |
| Backlog grows continuously | Arrival rate, processing time and worker capacity |
5. Review timeout and retry behavior together
Inspect job duration, worker timeout and the backend’s retry or visibility settings as one system. If work becomes available again while an earlier attempt is still executing, duplicate processing can occur.
Make side effects safe to retry where possible. For an export, use a stable job identifier and explicit completion state. For external requests, use the provider’s supported idempotency mechanisms when applicable.
Retries are not a substitute for fixing a persistent error. Before retrying a failed job, establish whether an earlier attempt already performed part of its work.
6. Verify the business result
A completed queue attempt is not always the full outcome. Check that the export file exists, the expected database state changed and the user can access the result. If the job triggers an external system, inspect that system’s evidence too.
Keep the user-facing state accurate: pending, running, completed or failed should reflect observable progress. A visible failure with a recovery route is better than a permanent “processing” message.
If the job is slow because it loads related records repeatedly, review Laravel N+1 queries. For AI work in the background, the ticket-classifier comparison discusses evaluation and failure handling separately from the queue transport.