When n8n executions stay queued, trace one execution from the main process through Redis to a worker and PostgreSQL before changing concurrency or retrying work. Confirm that workers are running the right command, share the queue and database identity, and can use the existing encryption key. Keep execution records and queue contents intact while diagnosing.
A working editor proves that the web process answers requests. It does not establish that a worker can consume jobs, read the database or decrypt a workflow's credentials. The quickest useful investigation narrows which of those boundaries failed.
Follow an execution, not just the dashboard
In n8n queue mode, the main process creates an execution and sends its ID through Redis. A worker picks it up, obtains workflow information from the database, executes it and writes results back. Both the broker and the database are therefore part of the execution path.
Choose one recent affected execution. Record its ID, workflow, trigger type, creation time, last status change and relevant deployment version. Use a restricted incident record: workflow input and output can contain personal information or credentials. Do not paste an unfiltered execution export into a public issue.
Distinguish queued work from a workflow deliberately waiting on a Wait node, a human response or an external callback. Also distinguish a job that never started from one that started and is slow or stuck inside a node. Those situations require different checks and have different retry risks.
| Observation | First boundary to inspect |
|---|---|
| All new production work waits | Worker process, Redis connectivity and matching queue settings. |
| One workflow stalls after starting | The last active node, external dependency and resource use. |
| Manual runs succeed, production runs wait | Whether manual runs use the same worker path. |
| Credential-dependent nodes fail on workers | Shared encryption key and credential access. |
| Only file-processing workflows fail | Binary data mode and availability from every worker. |
Establish process and readiness facts first
Review the recent change history: deployment, credential rotation, Redis migration, database maintenance, new worker or changed network policy. Record the exact main and worker image versions. Fix unintended version drift before attributing new behavior to capacity.
For a Compose deployment, use explicit file and project arguments. These commands inspect state; they do not restart or change it:
docker compose -f /path/to/n8n/compose.yaml \
-p your-n8n-project ps
curl --fail https://your-n8n.example/healthz/readinessThe monitoring reference distinguishes /healthz, which indicates reachability, from /healthz/readiness, which includes database connection and migration readiness. Worker health endpoints are disabled by default; enable the documented queue health setting deliberately and keep internal endpoints private.
Check the worker's launch configuration: a container with the n8n image is not sufficient if it starts another main process instead of the worker command. Inspect a short private log window around your execution ID and the last worker startup. Look for connection refusal, authentication failures, migration errors, out-of-memory termination and repeated process exits.
Do not dump printenv, complete container inspection output or expanded Compose configuration into a support transcript. Those can disclose database passwords, API keys and the encryption key.
Check that the producer and consumer share one queue
Compare the configured Redis host or cluster nodes, port, selected Redis database, key prefix, TLS setting and authentication identity on the main process and every worker. A healthy Redis connection to a different database or prefix can leave a worker idle while the intended queue grows.
The queue variable reference defines those settings. It also notes that a cluster-node configuration changes which connection settings apply. Do not compare only a hostname while ignoring an active cluster configuration.
From the relevant service network, establish DNS resolution, network reachability, authenticated Redis access and TLS trust. A Redis PING response is a narrow check, not proof that the n8n worker can reserve and complete jobs. Use your approved Redis client and credential method; avoid passwords in command arguments or copied URLs.
Inspect Redis memory pressure, rejected connections, connection limits and eviction behavior through your monitoring or authorised read-only client. Correlate changes with the first waiting executions. If the broker is failing under load, increasing workers can add connections and pressure before it helps throughput.
Download the non-destructive configuration comparator. It runs a read-only Node probe in the explicitly selected Compose services, compares relevant settings and reports field names that differ. Secret values use an ephemeral comparison digest internally; neither the values nor their fingerprints are printed.
python3 compare_config.py \
--compose-file /path/to/n8n/compose.yaml \
--project your-n8n-project \
--main n8n --workers workerThe comparator requires Python 3.9 or later and the Node runtime already in the n8n containers. It supports environment and file-based secrets plus the normal configuration-file key fallback. It does not cover every custom configuration provider, and equal configured values do not prove live connectivity or job consumption.
Check PostgreSQL access and the original encryption key
Verify that every worker uses the intended database host, database, schema, table prefix and role. A worker pointed at a different database can authenticate successfully but fail to find the execution created by the main process. The comparator checks these identities without displaying their values.
Review database connection failures, migration state, available connections and slow or blocked queries. Use an authenticated read-only session to confirm the database identity and inspect operational metrics. Preserve TLS validation; an untrusted certificate is a configuration problem to resolve, not a reason to disable verification.
Use the current n8n database support policy when selecting PostgreSQL versions. Queue mode with SQLite is not the recommended operating model. Avoid improvising a database migration during a backlog incident without a separate backup and recovery plan.
The main process and workers need the same existing N8N_ENCRYPTION_KEY to access encrypted credentials. Compare the effective secret sources privately. A worker that generated a different key or received a stale secret can fail even though its Redis and database connections work.
Do not generate a replacement key to fix the queue. Recover the original deployed key from the authorised secret store or backup, correct the affected process configuration and follow your normal controlled deployment procedure. A new random key does not decrypt credentials written under the old one.
For database-side symptoms, our PostgreSQL performance guide and connection pooling explanation can help frame the evidence. Adding a pooler or changing limits should follow diagnosis rather than become the first emergency change.
Treat file failures as a separate storage problem
Queue mode does not support persisted binary data in filesystem mode. A file present only on the main container's disk is not automatically available to another worker. This often explains why text-only workflows behave differently from document or attachment workflows.
External S3 binary storage is a licensed feature. As of 1 November 2026, the official external-storage documentation lists self-hosted Business and Enterprise availability, and says n8n will not start in S3 binary mode without a valid license. Do not recommend it as a free Community-mode fix.
That documentation officially supports AWS S3 and qualifies other compatible services separately. If evaluating another endpoint, test upload, worker read, historical execution access, retention and recovery against your exact version. No DanubeData endpoint compatibility result is implied here.
Changing the default storage mode does not automatically migrate old binary objects. Preserve access to the previous storage and design lifecycle rules around the retention required by execution history. A storage change that starts new jobs but breaks access to old executions is incomplete.
Recover with a canary and controlled retries
After fixing the identified boundary, run a tiny workflow with no external side effects. Make sure the test actually uses a worker. The queue variable reference documents OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS; a successful manual run on the main process is not evidence that the production queue works.
Observe the canary's creation, worker pickup, completion and stored result. Confirm the oldest waiting execution begins to advance and monitor backlog age as well as count. A smaller count can hide an old job that still never runs.
Before retrying existing executions, inspect what they may already have done. A worker can fail after a payment request or email was accepted but before n8n stored the response. Use downstream request IDs and idempotency support to prevent duplicates. Retry a small reviewed set before releasing an entire backlog.
Do not clear Redis, delete queue keys or manually rewrite execution records as a generic recovery procedure. Those actions remove evidence and can strand or duplicate work. If state repair becomes necessary, use a version-specific supported procedure with backups and a concrete recovery plan.
Improve alerts for worker exits, backlog age, database readiness, Redis pressure and failed executions. Compare the operational responsibilities in managed apps versus self-hosting. Explore DanubeData n8n hosting if a managed service fits, while checking its current version, plan and supported topology.
Frequently asked questions
Should I add workers immediately?
Only after distinguishing capacity from connectivity or configuration failure. More workers do not fix a wrong queue prefix, unavailable database or incorrect encryption key.
Why does the editor work while jobs wait?
The main process can serve the editor while the worker path is broken. Test worker pickup and completion explicitly.
Can rotating the encryption key clear stuck jobs?
No. It can make stored credentials unreadable. Restore the correct existing key source instead of replacing it arbitrarily.
Is S3 binary storage available without a paid license?
The current documentation lists Business and Enterprise self-hosted availability. Verify your edition and license before enabling it; use a supported architecture rather than bypassing the license check.
Sources
Queue architecture; queue settings; health checks; database configuration; licensed external storage.
