error fix

n8n Redis Connection Error: Fix Queue Mode Host, Port, Password, and Workers

A Redis connection error in n8n usually affects queue mode and means the main process or workers cannot reach Redis with the configured host, port, credentials, or network route.

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

A Redis connection error in n8n usually affects queue mode and means the main process or workers cannot reach Redis with the configured host, port, credentials, or network route.

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 Queue Mode Error: Fix Redis, Workers, Database, and Encryption Key Mismatches Related check n8n Queue Mode Setup: Redis, Postgres, Workers, and Encryption Key Checklist Still blocked? Generate a diagnostic brief

Problem Pattern

Queue mode cannot dispatch or process executions because one or more n8n processes cannot connect to Redis.

Version awareness

Last reviewed 2026-05-21

Applies to: self-hosted n8n, Docker, queue mode, Redis, workers, Postgres
Official docs checked: n8n Queue Mode
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

Redis role: Redis holds queued execution IDs for queue mode.
Default port: Redis commonly uses port 6379.
Required reachability: Main and worker processes must all reach Redis.
Credentials: Username, password, database, and TLS/network settings must match the Redis deployment.

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 Redis is running and reachable on the expected host and port.
Check QUEUE_BULL_REDIS_HOST and QUEUE_BULL_REDIS_PORT.
Check Redis username, password, and database variables if used.
Test network connectivity from the n8n main container and worker containers.
Restart n8n processes after changing Redis environment variables.

Verification

n8n logs show successful Redis connection.
Workers pick up queued executions.
Redis connection errors disappear from both main and worker logs.

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 expose Redis publicly to solve container networking.
If only workers cannot connect, compare worker environment variables against the main process.

Common Mistakes

Using localhost from inside a container.
Configuring Redis for the main process but not workers.
Forgetting Redis password or database index in one service.
Changing Redis host without restarting all n8n processes.

Examples

Redis variable check Keep these consistent across queue-mode processes.

QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_USERNAME=
QUEUE_BULL_REDIS_PASSWORD=change-me
QUEUE_BULL_REDIS_DB=0

FAQ

Does n8n need Redis outside queue mode?

Redis is specifically central to queue mode. If you are not using queue mode, troubleshoot the actual node or database error first.

Why does Redis work locally but not in Docker Compose?

The host name changes. In Compose, use the Redis service name on the shared network rather than localhost.

Sources

n8n Queue Mode Accessed 2026-05-08