error fix

n8n Worker Not Processing Jobs in Queue Mode

Check that main and worker processes use queue mode, share Redis, connect to the same database, use the same encryption key, and show healthy worker logs.

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, workers, Redis, Postgres
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

Check that main and worker processes use queue mode, share Redis, connect to the same database, use the same encryption key, and show healthy worker logs.

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.

Problem Pattern

Queue mode breaks when the main process, workers, Redis, database, or encryption key are not aligned. Jobs can queue up while workers look healthy but cannot read credentials or pull execution data.

Version awareness

Last reviewed 2026-05-21

Applies to: self-hosted n8n, Docker, queue mode, Redis, workers, Postgres
Official docs checked: n8n Queue Mode, n8n Queue Mode Environment Variables, n8n Executions
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, and queue worker expectations may shift after n8n upgrades.

Key Facts

Queue architecture: Main creates executions, Redis queues them, workers pick them up, and workers read/write execution data through the database.
Shared key: Workers need the main instance encryption key to access credentials.
Database recommendation: Postgres is recommended for serious queue-mode deployments.
Health signal: Queue mode can expose worker health and readiness endpoints when configured.

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.

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 instance and workers are all running with EXECUTIONS_MODE=queue.
Check Redis host, port, username, password, and database settings from both main and worker containers.
Confirm workers connect to the same n8n database as the main instance.
Verify N8N_ENCRYPTION_KEY is shared across main and worker processes.
Review worker logs and health checks for Redis, database, credential, or concurrency errors.

Verification

A test workflow execution is picked up by a worker.
Redis shows jobs moving instead of permanently waiting.
Worker logs show completed executions.
Credential-using workflows succeed on workers, not only on the main process.

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 QUEUE_BULL_REDIS_HOST DB_TYPE N8N_BINARY_DATA_MODE
docker compose exec worker printenv EXECUTIONS_MODE QUEUE_BULL_REDIS_HOST DB_TYPE N8N_BINARY_DATA_MODE

Secrets note: Do not print raw N8N_ENCRYPTION_KEY. Compare whether it 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, and encryption key status.

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
  N8N_ENCRYPTION_KEY: REDACTED_GENERATE_ONCE
  WEBHOOK_URL: https://automation.example.com/

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

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    environment: *n8n-env
    ports:
      - "5678:5678"

  worker:
    image: n8nio/n8n:latest
    restart: unless-stopped
    command: worker
    environment: *n8n-env

What to change: Use a real Postgres service and private secrets. Run the same image tag and encryption key on main and workers.
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.
Common mistakes: Different N8N_ENCRYPTION_KEY on worker. Different image versions across main and worker. Binary data not shared across processes.

Warnings

Do not scale worker count before confirming the database connection pool can handle it.
A worker without the correct encryption key may fail when a workflow needs credentials.
Filesystem binary data storage is not suitable for queue mode when workflows need persistent binary data.

Common Mistakes

Starting the main process in queue mode but not the worker.
Pointing workers at a different Redis or database.
Missing N8N_ENCRYPTION_KEY on workers.
Setting very low worker concurrency across too many workers.

Examples

Queue mode worker check All five checks must line up.

Main EXECUTIONS_MODE=queue: yes
Worker command: n8n worker
Redis reachable from worker: yes
Database same as main: yes
N8N_ENCRYPTION_KEY same: yes
Test execution processed: yes

FAQ

Why are jobs queued but workers idle?

Workers may not be connected to the same Redis queue, may not be in queue mode, or may fail readiness checks against Redis or the database.

Can this be fixed by adding more workers?

Only if workers are already healthy and capacity is the real bottleneck. Configuration issues get worse when you scale them.

Sources

n8n Queue Mode Accessed 2026-05-08 n8n Queue Mode Environment Variables Accessed 2026-05-08 n8n Executions Accessed 2026-05-08