n8n queue mode with Redis and Postgres#

The symptom that sends most teams here is not a single error message. It is a scaling pattern:

• the main n8n process becomes the bottleneck
• webhook latency grows under load
• one busy workflow blocks unrelated work
• you need more throughput without cloning the whole instance blindly

The root cause is that default single-instance execution stops being enough. Queue mode is n8n's documented scale-out model.

What queue mode actually does#

The n8n docs describe the flow like this:

1. the main instance receives the trigger or webhook
2. it passes the execution ID to Redis
3. a worker picks the job up
4. the worker reads workflow data from the database and executes it

That architecture is why queue mode scales better than just making one big main process.

The four requirements teams usually miss#

1. Use Postgres, not SQLite#

n8n's queue-mode docs recommend Postgres 13+ and explicitly say running queue mode with SQLite is not recommended.

If your self-hosted instance still uses SQLite, treat queue mode as a migration project, not just an environment-variable tweak.

2. Share the same encryption key#

The docs are very clear here: the main instance's encryption key must be shared with all worker and webhook processor nodes so they can access credentials stored in the database.

If you skip this, workers may be alive but unable to use credentials correctly.

3. Run Redis and point n8n at it#

Queue mode depends on Redis as the message broker.

At minimum, the docs show these environment variables for the main process:

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=localhost
QUEUE_BULL_REDIS_PORT=6379

If your Redis instance has auth or a non-default DB, you can also configure:

QUEUE_BULL_REDIS_USERNAME=...
QUEUE_BULL_REDIS_PASSWORD=...
QUEUE_BULL_REDIS_DB=0

4. Start actual worker processes#

Setting EXECUTIONS_MODE=queue is not enough by itself. The docs explicitly say you need worker processes so n8n can execute workflows.

That is the part people miss when they flip the env var and see no improvement.

The binary-data caveat that breaks migrations#

The queue-mode docs also call out an important restriction: n8n does not support queue mode with binary data stored in the filesystem.

If your workflows persist binary files, you need external storage such as S3 instead of assuming the local filesystem setup will keep working unchanged.

That single sentence in the docs matters more than a lot of blog-post boilerplate because it changes whether your migration is safe.

Minimal deployment checklist#

Use this as the first pass:

1. Migrate to Postgres if you are still on SQLite
2. Set and share the same encryption key across main and workers
3. Start Redis
4. Set EXECUTIONS_MODE=queue on the main instance and workers
5. Configure QUEUE_BULL_REDIS_HOST and QUEUE_BULL_REDIS_PORT
6. Start one or more worker processes
7. Move binary persistence off the filesystem if your workflows depend on it

What happens to webhooks in queue mode#

Queue mode does not remove webhook handling from the front door. The docs say the main or webhook process still receives the HTTP request, then hands execution off to a worker.

That means queue mode improves throughput, but it can also add some overhead and latency to the handoff. It is the right tradeoff when reliability and scaling matter more than doing everything in one process.

A realistic starting env file#

N8N_ENCRYPTION_KEY=replace-with-your-shared-key
EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379

Then make sure both the main instance and every worker use the same database, the same Redis, and the same encryption key.

When queue mode is the wrong next step#

If you are still debugging basic workflow logic, flaky credentials, or webhook registration, fix those first. Queue mode is a scaling tool, not a cure for broken workflow design.

These are the best companions if you are building a more production-ready n8n stack:

• n8n Complete Beginner Guide 2026: Build Your First Automation Workflow
• How I Fixed My n8n Workflow That Was Failing Silently for Three Weeks
• How I Stopped Missing Leads by Building a $0 CRM Automation in n8n
• How I Built a Client Reporting System That Runs Itself (With n8n)

References#

• n8n docs: Queue mode
• n8n docs: Queue mode environment variables