DEV Community

Cover image for n8n Queue Mode Checklist: Redis, Postgres 13+, Workers
Mahdi BEN RHOUMA
Mahdi BEN RHOUMA

Posted on Originally published at iloveblogs.blog

n8n Queue Mode Checklist: Redis, Postgres 13+, Workers

#n8n #queuemode #redis #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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

References

Originally published at https://www.iloveblogs.blog

Top comments (0)