Who this is for: Developers and DevOps engineers running n8n in production with Redis‑backed queue mode. We cover this in detail in the n8n Queue Mode Errors Guide.
Quick Diagnosis
| Action | Command / Setting |
|---|---|
| Check Redis version | redis-cli INFO server \| grep redis_version |
| Upgrade to ≥ 6.2 | docker pull redis:6.2-alpine && docker-compose up -d redis *(or apt/yum/helm)* |
| Clear old queue keys | redis-cli DEL n8n:queue:stream n8n:queue:pending |
| Restart n8n | docker restart n8n |
| If upgrade impossible → disable queue mode | queueMode: false in config.yml |
1. Why n8n Requires Redis ≥ 6.2
If you encounter any n8n queue mode unsupported node version resolve them before continuing with the setup.
n8n’s queue worker relies on newer Redis stream commands to safely re‑assign stalled jobs. Older versions lack the required semantics, which can cause duplicate execution or data loss.
Key Redis features used by n8n
| Feature | Introduced in Redis | n8n usage |
|---|---|---|
Streams (XADD, XREADGROUP) |
5.0 (basic) | Job ordering |
| Consumer Groups | 5.0 (stable) | Work distribution |
XCLAIM with MINID |
6.2 | Correct claim‑timeout handling |
XTRIM with MAXLEN (approx.) |
6.2 | Prevents unbounded stream growth |
EEFA Note: Running queue mode on an unsupported Redis version can silently corrupt workflow execution history. Never bypass the version check in production.
2. Determine Your Current Redis Version
If you encounter any n8n queue mode legacy version bug resolve them before continuing with the setup.
2.1. From the CLI
redis-cli INFO server | grep redis_version
2.2. From Docker
docker exec <redis_container> redis-cli INFO server | grep redis_version
2.3. From Kubernetes (helm chart)
kubectl exec -n <ns> <redis-pod> -- redis-cli INFO server | grep redis_version
Record the version string; you’ll need it for the upgrade matrix below.
3. Compatibility Matrix & Upgrade Paths
| Detected Version | Supported? | Recommended Target | Upgrade Method |
|---|---|---|---|
| 5.x – 6.0 | ❌ | 6.2.6 (LTS) or 7.x | In‑place package upgrade **or** replace container image |
| 6.1 | ❌ | 6.2.6 or later | Same as above |
| 6.2.x (≥ 6.2.0) | ✅ | Stay on latest 6.2.x or move to 7.x | No action required |
| 7.x | ✅ | Keep updated with minor releases | No action required |
3.1. In‑Place Upgrade (APT/YUM)
# Debian/Ubuntu sudo apt-get update && sudo apt-get install -y redis-server # RHEL/CentOS sudo yum update -y redis
Verify the new version:
redis-cli INFO server | grep redis_version
3.2. Container‑Based Upgrade
Update the image tag in your docker‑compose.yml:
services:
redis:
image: redis:6.2-alpine # ← bump tag
restart: unless-stopped
Pull the new image and restart the container:
docker-compose pull redis && docker-compose up -d redis
3.3. Helm Upgrade (Kubernetes)
helm repo update helm upgrade my-redis bitnami/redis \ --set image.tag=6.2.6-debian-10-r0 \ --namespace <ns>
EEFA Warning: Snapshot your Redis data (RDB/AOF) before any upgrade. In HA clusters, upgrade nodes **one at a time** and monitor replication lag.
4. Verify n8n Queue Mode After Upgrade
- Restart Redis (if not already done).
- Clear stale queue metadata (optional but recommended after a version jump):
redis-cli DEL n8n:queue:stream redis-cli DEL n8n:queue:pending
- Enable queue mode in
config.yml– keep the block concise:queueMode: true
queue: redis: host: localhost port: 6379 # password: yourPassword # optional - Start n8n and watch the logs for confirmation:
docker logs -f n8n # Look for: "Queue mode enabled – using Redis"
If the “Unsupported Redis version” message persists, double‑check that n8n is connecting to the upgraded instance (no stale DNS or port mapping).
5. Troubleshooting Checklist
| Task | How to Verify | Common Pitfall |
|---|---|---|
| Redis version ≥ 6.2 | redis-cli INFO server |
Connecting to an older replica instead of the primary |
| n8n config points to correct host/port | Review config.yml |
Environment variable overrides (REDIS_HOST) |
| No lingering old stream keys | redis-cli KEYS "n8n:queue:*" → should be empty after cleanup |
Old keys cause XCLAIM errors |
| Persistence enabled (RDB/AOF) | redis-cli CONFIG GET save |
Missing backups → data loss on upgrade |
| Network latency < 100 ms (recommended) | ping <redis-host> |
High latency can cause false “connection reset” errors |
EEFA Tip: Add a pre‑deployment health check that runs the version command and fails the pipeline if the version is < 6.2. This prevents accidental roll‑outs of incompatible Redis images.
6. Temporary Work‑Around When Upgrade Isn’t Possible
If you’re locked to an older Redis (e.g., legacy SaaS provider), you can fall back to the internal in‑memory queue:
queueMode: false # fallback to internal queue
What to expect
- Jobs are kept only in the process memory – a crash will lose pending work.
- Throughput may drop under heavy load because the in‑memory queue lacks Redis’ durability.
Best practice: Treat this as a short‑term mitigation. Open a ticket to upgrade Redis within the next sprint.
EEFA Caution: The in‑memory queue is not HA. Any crash will lose pending jobs.
Recap
| Action | Command / Setting |
|---|---|
| Check Redis version | redis-cli INFO server \| grep redis_version |
| Upgrade to ≥ 6.2 | docker pull redis:6.2-alpine && docker-compose up -d redis *(or apt/yum/helm)* |
| Clear old queue keys | redis-cli DEL n8n:queue:stream n8n:queue:pending |
| Restart n8n | docker restart n8n |
| If upgrade impossible → disable queue mode | queueMode: false in config.yml |
Follow these steps, verify the version, and n8n will run queue mode without the “Unsupported Redis version” error. Happy automating!
