error fix

n8n Queue Mode Error: Fix Redis, Workers, Database, and Encryption Key Mismatches

Queue mode errors usually come from inconsistent main/worker configuration, Redis connectivity, database access, version mismatch, encryption key mismatch, or unsupported binary storage assumptions.

Match your incident first

Start with the symptom you can prove

Jump to checks

Worker starts but does not process jobs

First check: Compare queue mode, Redis host/db, DB_TYPE, and n8n image tag between main and worker.

Wrong fix to avoid: Do not scale more workers before proving one worker shares the same queue and database.

Verify: A new queued execution changes from waiting to running on a worker and finishes.

Redis connection refused or ENOTFOUND redis

First check: From the worker network, run a Redis ping using the same host and port configured for n8n.

Wrong fix to avoid: Do not point workers at localhost unless Redis is inside the same container.

Verify: redis-cli ping returns PONG and worker logs stop reconnecting.

Jobs stay waiting or active forever

First check: Check worker logs, queue depth, CPU/memory, and the oldest waiting execution.

Wrong fix to avoid: Do not delete production Redis data until you have a backup and know the impact.

Verify: A fresh test execution starts promptly and the old stuck execution is handled intentionally.

Use when: self-hosted, queue mode
First check: Confirm main and worker processes share Redis, database, and N8N_ENCRYPTION_KEY.
Time to check: 5-10 minutes
Next step: Match the symptom, then run the verification checks.

Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.

Quick Answer

Queue mode errors usually come from inconsistent main/worker configuration, Redis connectivity, database access, version mismatch, encryption key mismatch, or unsupported binary storage assumptions.

Does this match your symptom?

Queue mode or workers are stuck

Jobs stay queued, workers look healthy but do not process executions, or Redis/database settings drift.

First check: Confirm main and worker processes share Redis, database, and N8N_ENCRYPTION_KEY.

Primary path n8n Worker Not Processing Jobs in Queue Mode Related check n8n Redis Connection Error: Fix Queue Mode Host, Port, Password, and Workers Related check n8n Queue Mode Setup: Redis, Postgres, Workers, and Encryption Key Checklist Still blocked? Generate a diagnostic brief

Problem Pattern

Queue mode starts but executions fail or never complete because main and worker processes do not share the same infrastructure assumptions.

Incident gates

Do not add workers until one worker passes these checks

Prepare queue brief

Queue-mode incidents get harder when worker count increases before the shared path is proven. Use these gates before scaling, replaying jobs, or changing workflow logic.

Gate	Pass condition	Stop if	Proof to keep
One worker path	A fresh production execution is queued, picked up by one known worker, and finishes.	Jobs stay waiting, only manual editor runs pass, or worker logs do not show pickup.	Execution ID, worker log timestamp, and completion status.
Shared infrastructure	Main and worker use the same Redis target, database target, image tag, and queue mode setting.	Any worker points at localhost, another Redis DB, another Postgres database, or a different image tag.	Redacted env parity checklist and Redis PONG from the worker network.
Secret parity	N8N_ENCRYPTION_KEY and runner auth expectations are confirmed privately without printing raw values.	Credentials fail only on workers or a raw env dump is needed to compare settings.	Yes/no parity notes or private fingerprints, never the secret values.
Worker-only features	Binary data mode and task runner sidecars are tested on the worker path when workflows use files or Code nodes.	The workflow uses filesystem-only binary data assumptions or Code nodes without matching runner sidecars.	One file read/write smoke test or one Code node smoke test handled by a worker.

If a gate fails, fix the shared path first. More workers, higher concurrency, or job replay can hide the root cause and increase database pressure.

Version awareness

Last reviewed 2026-06-06

Applies to: self-hosted n8n, Docker, queue mode, Redis, workers, Postgres
Official docs checked: n8n Queue Mode, n8n Queue Mode Environment Variables, n8n Task Runners, n8n Scaling Binary Data
Version-sensitive assumptions: n8n node parameters, credential names, and queue mode defaults can change between releases; confirm against your installed version before changing production.
What may change after upgrades: Node parameter names, credential scopes, webhook behavior, Docker image defaults, binary data modes, runner sidecar requirements, and queue worker expectations may shift after n8n upgrades.

Key Facts

Core components: Queue mode involves main process, Redis, workers, and database.
Required mode: EXECUTIONS_MODE=queue must be set consistently.
Shared secret: Main and worker processes need the same encryption key.
Database note: Distributed queue mode needs Redis and a shared database path; do not treat SQLite as the production target.
Manual execution trap: Manual editor runs may still execute on main unless OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS is enabled, so they can miss worker-only failures.
Task runners: External task runner mode needs a runner sidecar next to every worker that executes Code node tasks.

Production Diagnostic Matrix

Turn checks into a brief

Exact symptom or log	Likely cause	First check	Wrong fix to avoid	Verification
Worker starts but does not process jobs	Worker is connected to a different Redis, different database, or wrong queue settings than the main instance.	Compare queue mode, Redis host/db, DB_TYPE, and n8n image tag between main and worker.	Do not scale more workers before proving one worker shares the same queue and database.	A new queued execution changes from waiting to running on a worker and finishes.
Redis connection refused or ENOTFOUND redis	Redis service name, port, network, password, or startup order is wrong.	From the worker network, run a Redis ping using the same host and port configured for n8n.	Do not point workers at localhost unless Redis is inside the same container.	redis-cli ping returns PONG and worker logs stop reconnecting.
Jobs stay waiting or active forever	Workers are offline, concurrency is saturated, Redis state is stale, or a workflow step never completes.	Check worker logs, queue depth, CPU/memory, and the oldest waiting execution.	Do not delete production Redis data until you have a backup and know the impact.	A fresh test execution starts promptly and the old stuck execution is handled intentionally.
Credentials fail only on worker	Main and worker do not share the same N8N_ENCRYPTION_KEY or credential-related env vars.	Compare only safe variable names and fingerprints, not raw secret values, across main and worker.	Do not recreate all credentials before checking encryption key consistency.	The same credential works in an execution handled by a worker.
Binary data unavailable on worker	Binary data mode, filesystem volume, or external storage settings differ between main and worker.	Check binary data mode and whether the same storage path/bucket is mounted for every process.	Do not switch binary modes during an incident without a migration plan.	A workflow that writes and reads a file succeeds when handled by a worker.
Worker logs version mismatch or unknown node type	Main and worker run different n8n images or custom node installations.	Compare image tags and custom node directories between all n8n containers.	Do not upgrade only one worker in a queue-mode cluster.	All containers report the same n8n version and the failing node type loads on the worker.
Manual run succeeds in the editor, but production queue execution fails	Manual executions are still running on main, while production executions run on workers with different network, env, binary data, or task runner access.	Check OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS, then run a production-mode smoke test that must be picked up by a worker.	Do not mark queue mode ready from editor-only manual tests.	A production execution and, if enabled, an offloaded manual execution both complete on the expected worker path.
Code node works on main but fails or hangs on worker	External task runner sidecars, runner auth token, broker URI, allowed modules, or runner image version differ from the worker path.	Confirm the worker has a matching runner sidecar and that n8n and runner images use the same tested version.	Do not relax runner security settings or expose runner tokens before proving the sidecar topology.	A safe Code node smoke test completes on a queued worker execution without printing secrets.

Still blocked after these checks?

Use the brief to decide whether to keep fixing this setup, move the workload to n8n Cloud, or rebuild the self-hosted path on cleaner infrastructure.

Compare tools

Recommended Steps

Confirm the main process and workers run the same n8n version.
Confirm EXECUTIONS_MODE=queue is set where needed.
Confirm N8N_ENCRYPTION_KEY is identical across main and worker processes.
Check Redis host, port, credentials, and network access from all processes.
Check database connectivity from both main and worker processes.
Run a production-mode smoke execution that must be picked up by a worker.
If manual executions or Code nodes behave differently, check OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS and runner sidecars before changing workflow logic.
If binary data is involved, verify the active binary data mode and shared/external storage before replaying production jobs.

Verification

Workers connect to Redis and database on startup.
A production execution is picked up and completed by a worker.
Worker logs no longer show encryption, Redis, or database errors.
Manual and production smoke tests run on the expected process path.
A Code node smoke test completes on the worker path when external task runners are enabled.
A binary-data workflow can read and write data from the worker path without local filesystem drift.

First Commands / Checks

Read worker logs Use when jobs stay waiting or credentials fail only in production executions.

docker compose logs worker --tail=100

Secrets note: Redact payloads, credential names, and private hosts before sharing.
Verification: Worker logs show queue connection, execution pickup, or a specific Redis/database error.

Ping Redis from the compose network Use when Redis refused, jobs wait forever, or worker reconnects repeatedly.

docker compose exec redis redis-cli ping

Secrets note: If Redis requires auth, use a local shell and redact the auth value from notes.
Verification: Redis returns PONG from the expected service.

Compare safe main/worker variable names Use when main and worker behave differently.

docker compose exec n8n printenv EXECUTIONS_MODE OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS QUEUE_BULL_REDIS_HOST DB_TYPE N8N_DEFAULT_BINARY_DATA_MODE N8N_RUNNERS_ENABLED N8N_RUNNERS_MODE
docker compose exec worker printenv EXECUTIONS_MODE OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS QUEUE_BULL_REDIS_HOST DB_TYPE N8N_DEFAULT_BINARY_DATA_MODE N8N_RUNNERS_ENABLED N8N_RUNNERS_MODE

Secrets note: Do not print raw N8N_ENCRYPTION_KEY or N8N_RUNNERS_AUTH_TOKEN. Compare whether each is set using a private shell, then record only match/mismatch.
Verification: Main and worker use the same queue mode, Redis host, DB type, binary data mode, runner mode, and encryption key status.

Check worker readiness endpoint Use when health checks are enabled and you need to prove worker Redis and database readiness.

docker compose exec worker printenv QUEUE_HEALTH_CHECK_ACTIVE QUEUE_HEALTH_CHECK_PORT
docker compose exec worker node -e "fetch('http://127.0.0.1:' + (process.env.QUEUE_HEALTH_CHECK_PORT || 5678) + '/healthz/readiness').then(r => { console.log(r.status); process.exit(r.ok ? 0 : 1); })"

Secrets note: The readiness URL should not expose credentials, but keep internal hostnames out of shared incident notes.
Verification: The readiness endpoint returns success and worker logs show Redis and database connectivity.

Safe Copyable Config

Queue mode with Redis and one worker Use when production executions need worker isolation or more throughput.

x-n8n-env: &n8n-env
  DB_TYPE: postgresdb
  DB_POSTGRESDB_HOST: postgres
  DB_POSTGRESDB_DATABASE: n8n
  DB_POSTGRESDB_USER: n8n_app
  DB_POSTGRESDB_PASSWORD: REDACTED_CHANGE_ME
  EXECUTIONS_MODE: queue
  QUEUE_BULL_REDIS_HOST: redis
  QUEUE_HEALTH_CHECK_ACTIVE: "true"
  N8N_ENCRYPTION_KEY: REDACTED_GENERATE_ONCE
  WEBHOOK_URL: https://automation.example.com/

x-n8n-image: &n8n-image docker.n8n.io/n8nio/n8n:REPLACE_WITH_TESTED_VERSION

services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped

  n8n:
    image: *n8n-image
    restart: unless-stopped
    environment: *n8n-env
    ports:
      - "127.0.0.1:5678:5678"

  worker:
    image: *n8n-image
    restart: unless-stopped
    command: worker --concurrency=5
    environment: *n8n-env

What to change: Use a real Postgres service and private secrets. Run the same tested image tag and encryption key on main and workers. Adjust worker concurrency only after checking database pool capacity. Keep public HTTPS routing on the proxy; do not publish the raw n8n port as the queue fix.
Secrets to keep private: DB_POSTGRESDB_PASSWORD N8N_ENCRYPTION_KEY Redis auth if enabled
Verification: Worker logs show jobs being picked up. A production execution completes on the worker path. Worker readiness passes if QUEUE_HEALTH_CHECK_ACTIVE is enabled.
Common mistakes: Different N8N_ENCRYPTION_KEY on worker. Different image versions across main and worker. Binary data not shared across processes. Marking manual editor success as production worker proof.

Warnings

Queue mode adds operational complexity; do not enable it just to fix a simple workflow bug.
Different environment variables between workers can create confusing partial failures.
A manual editor execution can pass while production executions still fail on workers.
Do not use filesystem binary storage assumptions as a queue-mode fix; verify a supported shared or external binary data path.
Do not expose Redis publicly or open the raw n8n port while trying to make workers process jobs.

Common Mistakes

Setting queue mode on the main process but not workers.
Using different encryption keys across processes.
Forgetting Redis credentials in one environment.
Running workers against a different database or version.
Calling queue mode healthy after only a manual editor run.
Adding worker replicas before proving one worker can drain a new production execution.
Leaving worker examples on a floating latest image tag.
Enabling external task runners on main but not beside workers that execute Code nodes.

Examples

Queue mode environment parity Compare these between main and workers.

N8N_ENCRYPTION_KEY=same private value
EXECUTIONS_MODE=queue
DB_TYPE=postgresdb
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379
N8N_DEFAULT_BINARY_DATA_MODE=same supported mode
N8N_RUNNERS_ENABLED=same expectation
n8n image tag=same tested version

Queue incident triage order Use this order before changing concurrency or rebuilding containers.

1. Main and worker image tags match
2. Main and worker use EXECUTIONS_MODE=queue
3. Redis ping works from the worker network
4. Main and worker point at the same database
5. Encryption key parity is confirmed privately
6. One production execution is created and picked up by one worker
7. Code node and binary data paths are tested only if the workflow uses them

FAQ

Why do workers start but fail executions?

They may connect to Redis but fail database access, encryption, binary data access, or version compatibility during execution.

Should I use queue mode for a small instance?

Usually no. Queue mode is for scaling execution processing and requires Redis, workers, database planning, and monitoring.

Why does a manual run pass while production jobs fail?

Manual executions can run on the main process unless manual offloading is enabled. Use a production-mode smoke test to prove the worker path.

Why do Code nodes fail only on workers?

If external task runners are enabled, each worker that executes Code node tasks needs a matching runner sidecar, compatible runner image, and private auth token configuration.

Sources

n8n Queue Mode Accessed 2026-06-06 n8n Queue Mode Environment Variables Accessed 2026-06-06 n8n Task Runners Accessed 2026-06-06 n8n Scaling Binary Data Accessed 2026-06-06