n8n queue mode incorrect environment mode – EXECUTIONS_MODE vs EXECUTIONS_PROCESS

n8n Queue Mode Errors / Leave a Comment
Step by Step Guide to solve n8n queue mode incorrect environment mode
Step by Step Guide to solve n8n queue mode incorrect environment mode

Who this is for: n8n administrators and DevOps engineers who manage multiple n8n environments (dev, staging, prod) and need to guarantee that workflow executions stay within the correct queue. We cover this in detail in the n8n Queue Mode Errors Guide.

Quick Diagnosis

Symptom Likely Cause One‑line Fix
Production jobs appear in the dev queue (or vice‑versa) `QUEUE_MODE` does not match the current `NODE_ENV` Align `QUEUE_MODE` with `NODE_ENV` and restart the n8n service
“Queue mode mismatch” error in logs (Error: Queue mode does not match environment) Missing or mistyped env var (`QUEUE_MODE=production` vs `QUEUE_MODE=prod`) Correct the variable name/value in .env or Docker‑Compose
Staging jobs are processed by production workers `QUEUE_MODE` forced to `production` in a staging deployment Override `QUEUE_MODE=staging` in the staging compose file

Set QUEUE_MODE to development, staging, or production so it matches NODE_ENV. Restart n8n and confirm with GET /health/queue-mode – the response should show the same mode as your environment.

1. How n8n Determines Queue Mode ?

Micro‑summary: n8n reads two environment variables; QUEUE_MODE selects the Redis namespace, while NODE_ENV defines the overall runtime profile. If you encounter any n8n queue mode environment variable missing resolve them before continuing with the setup.

Variable Accepted Values Effect
`NODE_ENV` `development` | `staging` | `production` Sets logging level, debug tools, etc.
`QUEUE_MODE` `development` | `staging` | `production` Chooses the queue namespace (n8n:dev, n8n:stage, n8n:prod). If omitted, n8n falls back to NODE_ENV.

EEFA note: In production always set QUEUE_MODE=production. Relying on fallback can be overridden by an accidental .env file on a staging host, causing cross‑environment job leakage.

2. Symptoms of a Wrong Environment Mode

Micro‑summary: Look for cross‑environment execution, rate‑limit anomalies, and mismatched health‑check data.

  1. Cross‑environment job execution – Production UI jobs are picked up by dev workers.
  2. Unexpected rate‑limits – Dev queues have lower concurrency; production jobs stall.
  3. Log noise – Production logs contain [DEV] tags, confusing alerts.
  4. Health‑check mismatch – GET /health/queue-mode returns a mode that doesn’t match the service URL.

If any appear, proceed to verification.

3. Verify Current Queue Mode

3.1 Inspect environment variables inside the container

# Docker
docker exec -it n8n_container env | grep -E 'NODE_ENV|QUEUE_MODE'
# Kubernetes pod
kubectl exec -it $(kubectl get pod -l app=n8n -o jsonpath="{.items[0].metadata.name}") -- env | grep -E 'NODE_ENV|QUEUE_MODE'

3.2 Call the health endpoint

curl -s http://localhost:5678/health/queue-mode | jq .

Expected JSON:

{
  "queueMode": "production",
  "nodeEnv": "production"
}

EEFA warning: Do not expose /health/queue-mode publicly. Restrict it to internal IPs or protect it with an auth token.

3.3 Cross‑reference with deployment config

Make sure the values printed match the intended environment (development, staging, production).

4. Correct Configuration per Environment

Below are minimal, production‑ready snippets. Each block is limited to 4‑5 lines and is preceded by a short description.

4.1 Development (local Docker)

*Use an in‑memory queue and run executions in the main process.*

services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      - NODE_ENV=development
      - QUEUE_MODE=development
      - EXECUTIONS_PROCESS=main
    ports:
      - "5678:5678"

4.2 Staging (Docker Swarm / Kubernetes)

*Isolate staging jobs with a dedicated Redis instance.*

services:
  n8n:
    image: n8nio/n8n:2.0.0
    environment:
      - NODE_ENV=staging
      - QUEUE_MODE=staging
      - REDIS_URL=redis://redis-staging:6379
    deploy:
      replicas: 3

4.3 Production (Kubernetes Helm)

*Pin the image, enforce resource limits, and keep a PodDisruptionBudget.*

n8n:
  env:
    NODE_ENV: production
    QUEUE_MODE: production
    REDIS_URL: redis://redis-prod:6379
  resources:
    limits:
      cpu: "4"
      memory: "8Gi"
  replicaCount: 5

Key points for all environments

  • Never set QUEUE_MODE=production in a non‑production deployment.
  • Use a dedicated Redis instance per environment to keep namespaces isolated.
  • In production, lock the image tag (n8nio/n8n:2.0.0) to avoid accidental upgrades.
  • If you encounter any n8n queue mode proxy configuration error resolve them before continuing with the setup.

5. Troubleshooting Checklist

Check How to Verify Fix if Failing
Env vars are present docker exec … env \| grep QUEUE_MODE Add missing var to .env, Docker‑Compose, or Helm values
Values match (QUEUE_MODE = NODE_ENV) Compare printed values Align them (both production, staging, or development)
Redis namespace correct redis-cli KEYS "n8n:*" – look for n8n:prod vs n8n:dev Adjust QUEUE_MODE and restart workers
Worker pods use correct config kubectl describe pod <worker> → env section Redeploy with corrected Helm chart
Health endpoint reports correct mode curl …/health/queue-mode Restart n8n after fixing env vars
No stray .env files git ls-files | grep .env Remove or rename files on staging/production hosts

EEFA note: After any change, flush the old‑mode queue to avoid orphaned jobs.

# Example for Redis – delete keys from the dev namespace
redis-cli -n 0 KEYS "n8n:dev:*" | xargs -r redis-cli -n 0 DEL

Run this only during a maintenance window; deleting the wrong keys can lose in‑flight executions.

6. When to Use Explicit QUEUE_MODE Overrides

Scenario Recommended Setting
Hybrid CI/CD pipelines where the same Docker image runs in both staging and prod Set QUEUE_MODE via runtime overrides (docker run -e QUEUE_MODE=staging …) rather than baking it into the image.
Feature‑flag testing that needs a temporary dev queue in prod Use QUEUE_MODE=development only on a dedicated “sandbox” worker pool, isolated by a separate Redis DB (REDIS_URL=redis://redis-sandbox:6379).
Multi‑tenant SaaS with per‑tenant queue namespaces Prefix the mode with tenant ID (QUEUE_MODE=production-tenant42). See the sibling page “n8n queue mode custom namespace” for implementation details.

 

Bottom Line

The “wrong environment mode” error is always a mis‑aligned QUEUE_MODE / NODE_ENV pair. Explicitly set both variables in your deployment manifest, verify with the health endpoint, and purge any stray queues before restarting. Following the checklist guarantees that each n8n instance processes only the jobs meant for its environment, preserving data integrity and operational stability.

Must Read

Leave a Comment

Your email address will not be published. Required fields are marked *