The Error Message
Migrating keys between Redis instances using DUMP and RESTORE is usually straightforward, until you hit this wall:
(error) ERR DUMP payload version or checksum are wrong
Why is this happening?
You're likely facing one of two common issues. Either your Redis versions are incompatible, or the binary data was mangled during the transfer.
- Forward Compatibility Issues: Redis is great at reading older data (backward compatibility), but it can't predict the future. If you dump a key from Redis 7.0 (which uses RDB version 10) and try to restore it on Redis 6.2 (RDB version 9), it will fail. The older server simply doesn't understand the newer format.
- Binary Corruption: The
DUMPcommand outputs raw binary data. If you copy-paste this from a terminal or save it as a standard UTF-8 text file, you'll probably lose null bytes or corrupt special characters. Even a single bit change makes the checksum invalid.
How to Fix It
1. Verify Your Redis Versions
Start by checking the version on both your source and destination servers. Run this on both instances:
redis-cli INFO Server | grep redis_version
If your source is running a higher major version than your destination, RESTORE is guaranteed to fail. For example, moving data from Redis 7.2 back to 6.0 is a no-go for DUMP payloads.
2. Use the MIGRATE Command
If the servers can communicate directly over the network, stop using DUMP and RESTORE manually. The MIGRATE command is atomic and handles the transfer internally, bypassing encoding headaches entirely.
# Syntax: MIGRATE host port key destination-db timeout [COPY] [REPLACE]
To move a key named user:profile:100 to a server at 10.0.0.5, use:
MIGRATE 10.0.0.5 6379 "user:profile:100" 0 2000 COPY
The 2000 is a 2-second timeout. The COPY flag keeps the key on the source—essential for safe migrations.
3. Handle Binary Data Correctly in Code
When writing scripts, treat the payload as a byte array, never a string. In Python, ensure you're using bytes mode to avoid accidental encoding conversions:
import redis
# Connect without auto-decoding
src = redis.Redis(host='source-db', decode_responses=False)
dst = redis.Redis(host='dest-db', decode_responses=False)
key_name = "session:active:99"
raw_payload = src.dump(key_name)
if raw_payload:
try:
# 0 means no expiration; use replace=True to overwrite existing keys
dst.restore(key_name, 0, raw_payload, replace=True)
print("Transfer successful")
except redis.exceptions.ResponseError as e:
print(f"Migration failed: {e}")
4. Moving Data to an Older Version
If you must downgrade (e.g., moving from a cloud provider's Redis 7 to an on-prem Redis 6), DUMP won't work. You have two real options:
- Logical Migration: Write a script to fetch the data using type-specific commands like
HGETALLfor hashes orLRANGEfor lists. Then, re-insert them into the destination usingHSETorRPUSH. It's slower but version-independent. - Upgrade the Destination: The most stable fix is to upgrade the destination Redis to match or exceed the source version. This avoids all compatibility issues.
Verification
Test with a simple string to isolate the problem. If a basic string fails, you're almost certainly dealing with a version mismatch.
# On Source
SET debug_key "test"
DUMP debug_key
# Example output: "\x00\x04test\n\x00\xbd\xc6\x1e\x96\x9c\x13\xf6\xec"
# On Destination
RESTORE debug_key 0 "\x00\x04test\n\x00\xbd\xc6\x1e\x96\x9c\x13\xf6\xec"
# Should return OK
Pro Tips and Prevention
Don't trust the clipboard. Copying binary data from a terminal often adds hidden characters or strips null bytes. If you must use files, use redis-cli --raw DUMP key > key.bin to ensure the output isn't modified by terminal locale settings.
I always verify my migration files before importing. You can use the Hash Generator on ToolCraft to create a SHA-256 checksum of your exported data. Comparing the hash before and after the transfer ensures not a single byte was lost during the scp or rsync process.