gwhitdev / laravel-queue-doctor
Diagnose Laravel queue health and web-tier store reachability: catch worker/connection mismatches, stalled backlogs, and the cache/session Redis outages that 500 every request.
Maintainers
Requires
- php: ^8.2
- illuminate/console: ^11.0 || ^12.0 || ^13.0
- illuminate/support: ^11.0 || ^12.0 || ^13.0
Requires (Dev)
- orchestra/testbench: ^9.0 || ^10.0 || ^11.0
- pestphp/pest: ^3.0 || ^4.0
README
A single Artisan command — php artisan queue:doctor — that catches the three queue/infra failure modes Laravel itself stays quiet about:
- Worker/connection mismatch — jobs dispatch to one connection (say
redis) but the only running worker drains another (saydatabase). Jobs pile up forever and nothing errors. They just never run. - Stalled backlog — a connection has old pending jobs and no worker is draining them (dead worker, wrong supervisor config, scaled-to-zero).
- Web-tier store outage — your cache or session backend (often Redis) is unreachable. This is the nastiest one: it
500s every single request throughStartSession/the cache repository, long before any queue symptom appears — and a queue health check that only looks at the queue is blind to it.
Why this exists
This was extracted from a production Laravel app after a multi-hour outage with a frustratingly simple root cause: jobs were dispatched to Redis, but the worker was started as queue:work database. No exception, no failed job, no log line — work simply vanished into a queue nobody was draining. A second incident came from the other direction: Redis (backing both session and cache) dropped its connection, and StartSession turned every route into a 500 while the queue looked perfectly healthy.
queue:doctor is the check we wished we'd had: it asserts the connection you dispatch to is the one a worker is actually draining, and it round-trips the cache/session backends every request depends on.
Installation
composer require garethwhitleychard/laravel-queue-doctor
The service provider is auto-discovered. No config or migration to publish.
Usage
php artisan queue:doctor
Example output:
Default connection: redis (driver: redis)
Failed jobs: 0
+----------------------+----------+---------+------------+
| Connection | Driver | Pending | Oldest job |
+----------------------+----------+---------+------------+
| redis (default) | redis | 0 | — |
| database | database | 0 | — |
+----------------------+----------+---------+------------+
Workers draining: redis
+----------------+----------------+--------+---------------+
| Web-tier store | Backend | Status | Detail |
+----------------+----------------+--------+---------------+
| cache | redis (redis) | ok | round-trip ok |
| session | redis (default)| ok | reachable |
+----------------+----------------+--------+---------------+
Queue healthy: default connection 'redis' has no backlog.
Options
| Option | Default | Description |
|---|---|---|
--max-age |
3600 |
Age in seconds above which a backlog on the default connection is treated as a hard failure rather than a transient warning. |
Exit codes
queue:doctor exits non-zero on a mismatch, a stalled backlog, or an unreachable web-tier store — so it drops straight into CI, a deploy gate, or a cron-driven healthcheck:
# fail a deploy / alert if the queue or its backing stores are unhealthy php artisan queue:doctor || notify-oncall "queue:doctor failed"
How the worker detection works
Worker discovery parses the process list (ps -eo args) for queue:work/queue:listen and reads the connection argument. It is best-effort: in environments where the process list isn't visible (some containers, restricted hosts) it reports "could not inspect process list" and skips the mismatch verdict rather than producing a false alarm. The backlog and store checks still run.
Failing over a downed store
When queue:doctor reports WEB-TIER STORE DOWN, the fastest recovery that keeps the app serving is to move off the broken backend until it recovers:
CACHE_STORE=database SESSION_DRIVER=cookie
Testing
composer install vendor/bin/pest
License
MIT. See LICENSE.