n8n queue mode environment variable missing – EXECUTIONS_MODE and QUEUE_BULL_REDIS_HOST fix

Who this is for: Ops engineers, DevOps specialists, and platform developers who run n8n in production‑grade queue mode and need a reliable, repeatable fix for missing environment‑variable errors. We cover this in detail in the n8n Queue Mode Errors Guide.

Quick Diagnosis

Problem: n8n starts in queue mode but aborts with errors such as:

Error: Required environment variable "EXECUTIONS_PROCESS" is not set

or

Error: Missing required queue‑mode variable “QUEUE_BULL_REDIS_HOST”

Featured‑snippet solution – Define the missing variables in the runtime environment (.env, Docker/K8s manifest, or systemd service) and restart n8n. The queue re‑activates and workers resume processing.

1. Why Queue Mode Needs Extra Variables ?

If you encounter any n8n queue mode incorrect environment mode resolve them before continuing with the setup.

Queue mode separates the Web UI (EXECUTIONS_PROCESS=main) from the execution workers (EXECUTIONS_PROCESS=worker). Coordination is performed through a Redis‑backed Bull queue. If any required flag or Redis credential is absent, n8n exits before connecting to the broker.

EEFA note – Never rely on the default in‑memory broker in production; always supply explicit Redis credentials to avoid silent data loss during container restarts.

2. Mandatory Environment Variables

Variable	Purpose
EXECUTIONS_PROCESS	Switches n8n to main (UI) or worker role
QUEUE_MODE	Enables the queue subsystem (true required)
QUEUE_BULL_REDIS_HOST	Redis host address (URL or hostname)
QUEUE_BULL_REDIS_PORT	Redis TCP port (if not embedded in URL)
QUEUE_BULL_REDIS_PASSWORD	Redis password (optional but recommended)
QUEUE_BULL_REDIS_DB	Redis DB index dedicated to the queue
N8N_LOG_LEVEL	Log verbosity (info or debug)

Variable	Typical Value	Example
EXECUTIONS_PROCESS	worker or main	EXECUTIONS_PROCESS=worker
QUEUE_MODE	true	QUEUE_MODE=true
QUEUE_BULL_REDIS_HOST	redis://redis:6379	QUEUE_BULL_REDIS_HOST=redis://redis:6379
QUEUE_BULL_REDIS_PORT	6379	QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD	<secret>	QUEUE_BULL_REDIS_PASSWORD=SuperSecret123
QUEUE_BULL_REDIS_DB	0 or 1	QUEUE_BULL_REDIS_DB=1
N8N_LOG_LEVEL	debug or info	N8N_LOG_LEVEL=debug

EEFA – Never commit real passwords to source control. Use Docker secrets, Kubernetes Secret objects, or a vault solution.

3. Setting the Variables: Deployment‑Specific Guides

3.1 Docker Compose (most common)

Define the service and its environment

services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      - EXECUTIONS_PROCESS=worker
      - QUEUE_MODE=true

Add Redis connection details

      - QUEUE_BULL_REDIS_HOST=redis://redis:6379
      - QUEUE_BULL_REDIS_PASSWORD=${REDIS_PASSWORD}
      - N8N_LOG_LEVEL=debug
    depends_on:
      - redis

Add the Redis container and expose ports

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]
    environment:
      - REDIS_PASSWORD=SuperSecret123
    ports:
      - "6379:6379"

Store the password in an .env file (Docker Compose loads it automatically):

REDIS_PASSWORD=SuperSecret123

3.2 Kubernetes (Helm or raw manifests)

Deployment metadata and replica count

apiVersion: apps/v1
kind: Deployment
metadata:
  name: n8n
spec:
  replicas: 2
  selector:
    matchLabels:
      app: n8n

Pod template with container image

  template:
    metadata:
      labels:
        app: n8n
    spec:
      containers:
        - name: n8n
          image: n8nio/n8n:latest

Inject required environment variables

          env:
            - name: EXECUTIONS_PROCESS
              value: "worker"
            - name: QUEUE_MODE
              value: "true"
            - name: QUEUE_BULL_REDIS_HOST
              value: "redis://redis:6379"
            - name: QUEUE_BULL_REDIS_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: redis-secret
                  key: password
            - name: N8N_LOG_LEVEL
              value: "debug"

Create the secret that holds the Redis password

kubectl create secret generic redis-secret \
  --from-literal=password=SuperSecret123

3.3 Bare‑metal / Systemd

Create a .env file next to the binary

# /opt/n8n/.env
EXECUTIONS_PROCESS=worker
QUEUE_MODE=true
QUEUE_BULL_REDIS_HOST=redis://127.0.0.1:6379
QUEUE_BULL_REDIS_PASSWORD=SuperSecret123
N8N_LOG_LEVEL=info

Reference the file in a systemd unit

[Service]
EnvironmentFile=/opt/n8n/.env
ExecStart=/usr/local/bin/n8n start
Restart=always

Reload systemd and restart n8n

systemctl daemon-reload
systemctl restart n8n

4. Verifying Queue Mode Activation

4.1 Process role & queue flag

Check	Command	Expected output
Role	docker exec <c> printenv EXECUTIONS_PROCESS	worker (or main)
Queue flag	docker logs <c> | grep “Queue mode enabled”	Queue mode enabled

4.2 Redis connectivity & worker heartbeat

Check	Command	Expected output
Redis connection	docker exec <c> curl -s http://localhost:5678/rest/workflows -o /dev/null && echo OK	OK
Worker heartbeat	docker logs <c> | grep “Worker started”	Worker started, listening on queue

If any check fails, double‑check variable spelling, secret mounting, and network reachability. If you encounter any n8n queue mode proxy configuration error resolve them before continuing with the setup.

5. Production‑Grade EEFA Considerations

Issue	Why it Happens	Production fix
Variable typo (e.g., QUEUE_BULL_REDIS_HOSTS)	Human error; n8n treats it as missing	Add a CI lint step (dotenv-linter) that validates required vars against a schema
.env not present in container	Dockerfile may copy source but not runtime file	Mount the file as a volume (-v ./env/.env:/home/node/.env) or use env_file in Compose
Redis password rotation	Secret rotation invalidates the stored password	Store password in a secret manager (AWS Secrets Manager, Vault) and perform a rolling restart
Scaling workers without updating EXECUTIONS_PROCESS	New pods start as main and compete for UI port	Set EXECUTIONS_PROCESS=worker only in the worker deployment; keep a single main for the UI
Log level left at debug in prod	Excessive log volume, possible PII leakage	Switch to N8N_LOG_LEVEL=info or warn after troubleshooting

6. Troubleshooting Checklist

• ☐ Verify all variables from Section 2 are present in the runtime environment.
• ☐ Confirm the Redis endpoint is reachable (nc -zv redis 6379).
• ☐ Ensure EXECUTIONS_PROCESS matches the intended role (main for UI, worker for execution).
• ☐ Check that Docker/K8s secrets are correctly mounted and not double‑base64‑encoded.
• ☐ Search logs for the exact error string (grep "missing environment variable").
• ☐ Restart n8n after any environment‑variable change; they are read only at process start.

---

Conclusion

Defining the required queue‑mode variables exactly as documented restores n8n’s execution engine and prevents silent failures. By injecting them through Docker Compose, Kubernetes manifests, or systemd units and by validating them with EEFA best practices you achieve a resilient, production‑ready queue configuration that scales safely and logs meaningfully. No additional tools or code are needed beyond the environment variables themselves.