Migrate n8n Redis Instance Safely in 5 Steps

n8n Redis errors / Leave a Comment

Redis Migration Flowchart for n8n

Step‑by‑Step Guide to Move Data Without Breaking Your Workflows in n8n Redis Instance

 

 

Who this is for: n8n operators who rely on Redis for queueing and caching and need to relocate the Redis service with minimal downtime. For a complete overview of Redis usage, errors, performance tuning, and scaling in n8n, check out our detailed guide on Redis for n8n Workflows.

Quick Diagnosis

  1. Take a live RDB/AOF snapshot on the old server (redis-cli --rdb /tmp/dump.rdb or copy the AOF file).
  2. Spin up the new Redis (same version, matching maxmemory, appendonly yes).
  3. Copy the snapshot/AOF to the new host (scp dump.rdb new‑host:/var/lib/redis/).
  4. Stop the old Redis, start the new one, and update n8n’s REDIS_HOST (or the DNS CNAME you use).
  5. Validate with redis-cli ping and a quick n8n workflow run.
  6. Rollback by pointing REDIS_HOST back if anything fails.

Result: Zero data loss, <30 s downtime, and n8n continues processing jobs without manual intervention.

1. Why a Dedicated Migration Guide?

The pillar article Common Redis Errors in n8n explains what happens when Redis is unreachable, but it doesn’t cover the operational steps required to relocate the Redis service itself. This page fills that gap by providing a production‑grade migration workflow that minimizes downtime, preserves all workflow data, and keeps n8n’s job queue intact.

EEFA note – Skipping the AOF/RDB snapshot or using a mismatched Redis version can corrupt the job queue, causing lost executions. Always test the migration in a staging environment first.

2. Prerequisites & Checklist

 

Cron Triggered Data Sync Workflow

 


Micro‑summary: Verify you have the right version, access, and safety nets before touching production.

Item Details
Current Redis version redis-cli INFO SERVER | grep redis_version – must match on the target host (or use compatible major version).
n8n version ≥ 1.0 (uses Redis for queue & cache).
Access SSH to both old and new servers, redis-cli installed locally.
Backup storage At least 2× the size of your Redis dataset for safety.
DNS / Env var Identify whether n8n uses a DNS CNAME (REDIS_HOST=redis.mycompany.com) or a raw IP.
Maintenance window Optional but recommended for high‑traffic installations.
Rollback plan Keep the original Redis running until you confirm success.

3. Create a Consistent Snapshot of the Source Redis

Micro‑summary: Capture an exact point‑in‑time copy of the Redis data using the persistence mode that matches your workload.

3.1 Choose the Persistence Mode

Mode When to use Command
RDB (point‑in‑time dump) Small‑to‑medium datasets, low write throughput redis-cli --rdb /tmp/dump.rdb
AOF (append‑only file) Large datasets, need exact write order cp /var/lib/redis/appendonly.aof /tmp/appendonly.aof

EEFA – If you have both RDB and AOF enabled, copy both files. n8n relies on the exact queue order; an AOF‑only restore guarantees no job loss.

3.2 Verify the Snapshot

Run the built‑in Redis tools to ensure the files are not corrupted before moving them.

# Verify RDB file integrity
redis-check-rdb /tmp/dump.rdb && echo "RDB OK"

# Verify AOF file integrity (auto‑fixes if needed)
redis-check-aof --fix /tmp/appendonly.aof && echo "AOF OK"

If either check fails, abort and investigate the corruption before proceeding. If you run into an cache, first check out this troubleshooting guide Redis vs alternative caches for n8n. Once you’ve fixed it, you can continue with the setup.

4. Provision the New Redis Server

Micro‑summary: Install the same Redis version and clone the critical configuration parameters.

  1. Install the same major version (e.g., apt-get install redis-server=6.2.*).
  2. Mirror the configuration (/etc/redis/redis.conf) – especially maxmemory, maxmemory-policy, appendonly, save directives.
  3. Open the same port (default 6379) and allow traffic from the n8n host(s) in the firewall.

To confirm the important settings, run a quick diff on the live config:

# Show memory, persistence, and snapshot settings
grep -E 'maxmemory|appendonly|save' /etc/redis/redis.conf

EEFA – Do not enable protected-mode yes unless you also configure a proper bind address; otherwise n8n will be blocked.

5. Transfer the Snapshot to the New Host

Micro‑summary: Securely copy the dump files and set correct ownership.

# Transfer RDB (or AOF) to the new server
scp /tmp/dump.rdb new-redis:/var/lib/redis/
# If using AOF instead:
# scp /tmp/appendonly.aof new-redis:/var/lib/redis/

# Ensure the redis user owns the files
ssh new-redis "chown redis:redis /var/lib/redis/dump.rdb /var/lib/redis/appendonly.aof"

6. Stop the Old Instance & Load the Snapshot

Micro‑summary: Shut down the source Redis, then start the new instance so it loads the transferred data.

# On old host – stop Redis to freeze writes
systemctl stop redis

# Verify no clients can connect (expected to fail)
redis-cli -h <old‑host> ping   # should return (nil) or connection refused

# On the new host – start Redis, which will load the AOF (preferred) or RDB
systemctl start redis
redis-cli ping   # should return PONG

If both RDB and AOF were copied, Redis will automatically prefer the AOF and ignore the RDB.

7. Switch n8n to the New Redis Endpoint

Micro‑summary: Point n8n at the new Redis host and restart the service.

7.1 Update Environment Variable

# DNS CNAME (recommended)
export REDIS_HOST=redis-new.mycompany.com
# Or raw IP
# export REDIS_HOST=10.0.2.45

Restart n8n using your deployment method:

# Docker
docker restart n8n
# PM2
pm2 restart n8n
# systemd
systemctl restart n8n

7.2 Verify Connectivity

# From the n8n host, confirm Redis replies
redis-cli -h $REDIS_HOST ping   # should return PONG

Run a quick test workflow that enqueues a job and confirm the queue length grew:

# Check the n8n queue size after the test
redis-cli -h $REDIS_HOST LLEN n8n:queue   # should be > 0

8. Minimize Downtime – “Read‑Only” Mode Trick

Micro‑summary: Pause background workers while copying data to shrink the window of possible job loss.

  1. Set EXECUTIONS_PROCESS=main in n8n to stop background workers.
  2. Perform the snapshot & copy (steps 3‑5).
  3. Re‑enable workers by restoring EXECUTIONS_PROCESS=queue.

EEFA – Remember to revert EXECUTIONS_PROCESS after the migration; leaving it on main disables the queue entirely.

9. Post‑Migration Validation Checklist

Micro‑summary: Run a concise set of health checks to ensure everything is operating as expected.

Check Command / Action
Redis health redis-cli INFO replication – role:master
n8n connectivity redis-cli -h $REDIS_HOST ping
Queue integrity redis-cli -h $REDIS_HOST LLEN n8n:queue matches pre‑migration count
Workflow execution Run a known workflow; confirm success in UI and logs
Metrics Verify Prometheus/Grafana dashboards show normal request latency
Rollback If any check fails, point REDIS_HOST back to the old server and restart n8n

10. Rollback Procedure (if needed)

Micro‑summary: Quickly revert to the original Redis instance without data loss.

  1. Re‑apply the original REDIS_HOST value in the n8n environment.
  2. Restart n8n using the same method as before.
  3. Verify that the old Redis instance is still running (do not stop it until the new instance is proven stable).

EEFA – Keep the old Redis running for at least 30 minutes after migration; this gives you a safety net for any delayed jobs that may have been in flight.

11. Common Pitfalls & How to Avoid Them

Symptom Root Cause Fix
ERR unknown command ‘PING’ Connected to a non‑Redis service (e.g., a proxy) Verify $REDIS_HOST resolves to the correct IP and port.
Missing jobs after migration AOF not copied or disabled on new host Ensure appendonly yes is set and the AOF file is present.
n8n throws ECONNREFUSED Firewall blocks new host Open port 6379 inbound from n8n nodes.
High latency after switch New host has different maxmemory-policy causing evictions Mirror all memory‑policy settings from the source.

Next Steps

  • Automate future migrations with a Terraform or Ansible playbook (see sibling article “Automating n8n Redis provisioning”).
  • Enable Redis Sentinel for high‑availability to avoid future manual migrations.

*Happy migrating!*

Must Read

Leave a Comment

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