n8n Queue Mode Explained: When You Need It and How to Set It Up

n8n queue mode splits triggers from execution: a main instance, a Redis queue and workers. Here is when you need it, what it requires and how to set it up.

n8n Queue Mode Explained: When You Need It and How to Set It Up

Short answer: n8n queue mode splits the work. One main instance receives triggers and webhooks, Redis holds a queue of pending executions, and one or more workers run them. You need it when a single n8n process can’t keep up, not before. This guide explains how it works, when it’s worth it, and the exact settings from n8n’s queue mode docs.

What is n8n queue mode?

n8n queue mode is an execution mode where the main instance creates executions but doesn’t run them. It passes each execution ID to Redis, and the next free worker picks it up, loads the workflow from the database, runs it, saves the result and reports back. You scale up or down by adding or removing workers.

Here is the flow, as n8n documents it:

  1. The main instance handles timers and webhook calls and generates (but doesn’t run) an execution.
  2. It sends the execution ID to Redis, which keeps the queue.
  3. A free worker picks up the message.
  4. The worker reads the workflow from the database using the execution ID.
  5. When it finishes, the worker writes the results to the database and tells Redis.
  6. Redis notifies the main instance.

When do you need queue mode?

You need queue mode when executions start queuing up behind each other, when webhooks arrive in bursts, or when heavy workflows make the editor slow for everyone. If your instance runs a few thousand light executions a month without delays, a single instance is simpler and cheaper.

Some practical signals:

  • Executions wait. Scheduled or webhook runs start late because others are still running.
  • The UI lags during peaks. In single mode, the main process serves the editor and runs workflows, so a heavy job competes with the UI.
  • You want to scale horizontally. Adding a worker is easier than resizing one big server again and again.
  • You need webhook capacity. Queue mode is the base for separate webhook processors behind a load balancer.

If memory is your real problem, check how much RAM n8n needs first. Sometimes a bigger server or pruning execution data solves it without new moving parts.

SituationSingle instanceQueue mode
Light, steady workloadGood fitOverkill
Bursty webhooksCan fall behindAdd workers and webhook processors
Heavy workflows slow the editorCommonEditor and execution are separated
DatabaseSQLite or PostgresPostgres (SQLite not supported for distributed setups)
Extra parts to runNoneRedis, workers, shared encryption key

What do you need before enabling queue mode?

You need four things: a PostgreSQL database that every instance can reach, a Redis instance, the same N8N_ENCRYPTION_KEY on the main instance and every worker, and EXECUTIONS_MODE=queue set everywhere. Without the shared key, workers can’t decrypt the credentials stored in the database.

Two more points from the docs are easy to miss:

  • Binary data. n8n doesn’t support queue mode with binary data stored on the filesystem. If workflows need to keep binary data, use S3 external storage.
  • Licensing. n8n’s pricing page lists “Queue mode for scaling” under the Business plan and marks it as not included on Cloud Starter and Pro. Viewing running workers (Settings > Workers) and multi-main are Enterprise features. Check which edition you run before you plan around it.

How do you set up n8n queue mode?

Set EXECUTIONS_MODE=queue and the Redis host and port on the main instance and every worker, share the main instance’s encryption key, then start one or more processes with the worker command. Workers need access to both Redis and the database.

Step 1: Start Redis

The docs use the official Redis image. By default, Redis listens on port 6379 with no password, so keep it on a private network or set a password.

docker run --name some-redis -p 6379:6379 -d redis

Step 2: Configure the main instance

export EXECUTIONS_MODE=queue
export QUEUE_BULL_REDIS_HOST=localhost
export QUEUE_BULL_REDIS_PORT=6379
export N8N_ENCRYPTION_KEY=<main_instance_encryption_key>

Optional Redis settings include QUEUE_BULL_REDIS_USERNAME, QUEUE_BULL_REDIS_PASSWORD and QUEUE_BULL_REDIS_DB. QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD (default 10,000 ms) sets how long n8n waits for an unavailable Redis before exiting. The full list is on the queue mode environment variables page.

Step 3: Start workers

Give each worker the same environment (mode, Redis, database, encryption key), then start it. With Docker:

docker run --name n8n-queue -p 5679:5678 n8nio/n8n worker

Each worker runs 10 jobs in parallel by default. To change that:

n8n worker --concurrency=5

n8n recommends a concurrency of 5 or higher. Many workers with low concurrency can exhaust your database connection pool, which leads to delays and failures.

Step 4: Turn on health checks

Set QUEUE_HEALTH_CHECK_ACTIVE on workers to expose /healthz (is the worker up?) and /healthz/readiness (are its database and Redis connections ready?). Point your container orchestrator or uptime monitor at them.

Step 5 (optional): Add webhook processors

For heavy webhook traffic, run extra processes with the webhook command and put them behind a load balancer. Route /webhook/* and /webhook-waiting/* to the webhook pool, and everything else, including /webhook-test/*, to the main process. n8n advises against adding the main process to the webhook pool, because it degrades the editor.

docker run --name n8n-queue -p 5679:5678 -e "EXECUTIONS_MODE=queue" n8nio/n8n webhook

What are the trade-offs of queue mode?

Queue mode adds capacity but also latency and moving parts. Every production webhook execution passes through Redis to a worker, which n8n says adds some overhead. You also have to run, secure and back up Redis and Postgres, and keep every main and worker process on the same n8n version.

  • Large webhook responses travel from the worker back to the main instance inside a queue message. N8N_WEBHOOK_RESPONSE_RELAY_SIZE_MAX caps that at 64 MiB by default, and n8n suggests budgeting about 1.5 times that value in Redis memory per response in flight.
  • Graceful shutdown: workers get 30 seconds by default (N8N_GRACEFUL_SHUTDOWN_TIMEOUT) to finish jobs before stopping. Raise it if you run long workflows and deploy often.
  • Upgrades become a coordinated job. With n8n 3.0 on the way, read what breaks in n8n 3.0 before you upgrade a multi-process setup.

What does queue mode cost to host?

Self-hosted, queue mode costs whatever your extra processes cost: Redis, Postgres and one server or container per worker. A small setup can share one VPS; larger ones spread workers across machines. Our VPS comparison lists current server prices, and the n8n Cost & Hosting Planner estimates the server size for your volume.

If you don’t run n8n yet, start with our Docker Compose guide, get a single instance stable, and add queue mode only when the signals above appear.

Frequently asked questions

What is n8n queue mode?

Queue mode is an n8n execution mode where one main instance receives triggers and webhooks, puts each execution ID on a Redis queue, and separate worker instances pick up and run the executions. You scale by adding or removing workers.

Does n8n queue mode need Redis and Postgres?

Yes. Redis is the message broker that holds the queue, and the database stores workflow and execution data. n8n’s docs say running queue mode with SQLite isn’t recommended and a distributed setup over SQLite isn’t supported, so use PostgreSQL.

What concurrency should n8n workers use?

Each worker runs 10 jobs in parallel by default. n8n recommends a concurrency of 5 or higher, because many workers with low concurrency can exhaust your database connection pool and cause delays and failures.

Is queue mode available on n8n Cloud Starter or Pro?

No. n8n’s pricing page lists queue mode as not included on the Cloud Starter and Pro plans; it appears on the Business and Enterprise plans. Viewing running workers and multi-main are Enterprise features.

Do I need queue mode for a small n8n instance?

Usually not. A single instance handles light, steady workloads. Queue mode is worth the extra Redis, database and worker setup when executions pile up, webhooks arrive in bursts, or one heavy workflow slows down the editor for everyone.

Sources

n8n Docs: Enable queue mode; n8n Docs: Queue mode environment variables; n8n pricing (read 26 October 2026); n8n Docs: Manage execution data. This is a documentation-based guide, not a benchmark we ran.

hamid7777 Avatar

Written & tested by

The Sophrai brief

One calm email when something actually matters.

New tools, real cost breakdowns and the automation news worth your time. No hype, no spam.