🚨 Redis Error Guide: 'DUMP payload version or checksum are wrong' — Fix RESTORE Serialization Mismatches

Overview

Redis returns this error from RESTORE when the serialized blob you passed does not pass validation: either its embedded RDB version is newer than the target server understands, or the trailing CRC64 checksum does not match the bytes. DUMP produces an opaque, versioned, checksummed payload; RESTORE refuses to deserialize anything that looks corrupted or incompatible.

The literal error clients receive:

(error) ERR DUMP payload version or checksum are wrong

This is data-integrity protection working. The payload is fine over a matching, byte-clean path — so the error almost always means the bytes were altered in transit (encoding/whitespace), truncated, or generated by a Redis version too new for the target. It is not about the key name (BUSYKEY) or memory (OOM); it is strictly about the blob’s version tag and checksum.

Symptoms

• RESTORE fails immediately with DUMP payload version or checksum are wrong, regardless of whether the key exists.
• The same DUMP/RESTORE works within one server version but fails across versions or across a shell pipeline.
• Payloads copied through logs, JSON, or a UTF-8 channel fail, while a raw binary pipe succeeds.

redis-cli RESTORE user:42 0 "$PAYLOAD"

(error) ERR DUMP payload version or checksum are wrong

Common Root Causes

1. RDB version newer than the target

The payload was created by a newer Redis (higher RDB version) than the server you are restoring into; the older server can’t read it.

redis-cli -h SRC INFO server | grep -E 'redis_version|rdb_version'
redis-cli -h DST INFO server | grep -E 'redis_version'

Restoring from a newer major version into an older one is the classic trigger.

2. Binary-unsafe transport corrupted the bytes

The payload was passed through a channel that mangled bytes — shell quoting, a UTF-8/JSON round-trip, added newlines, or copy-paste — so the checksum no longer matches.

# The payload contains arbitrary binary; storing it in a normal string variable can corrupt it
echo "$PAYLOAD" | xxd | head

3. Truncated payload

The blob was cut off (partial read, buffer limit, a logging system that clipped it), so the checksum fails.

4. Payload not actually a DUMP output

The value passed to RESTORE was some other serialized form (a plain value, a re-encoded string) rather than the exact bytes from DUMP.

Diagnostic Workflow

Step 1: Compare source and target versions

redis-cli -h SRC INFO server | grep redis_version
redis-cli -h DST INFO server | grep redis_version

If the destination is older, that alone can cause the error — restore into an equal-or-newer version.

Step 2: Verify the payload survived transport intact

Pipe raw binary end to end rather than through a variable or text channel:

# Byte-clean pipe: DUMP straight into RESTORE, no intermediate string
redis-cli -h SRC --no-raw DUMP user:42 | wc -c        # length sanity check
redis-cli -h SRC DUMP user:42 | redis-cli -h DST -x RESTORE user:42 0 REPLACE

The -x flag reads the last argument from stdin as raw bytes, avoiding shell mangling.

Step 3: Check payload length against the source

redis-cli -h SRC STRLEN <(redis-cli -h SRC DUMP user:42) 2>/dev/null || \
redis-cli -h SRC DUMP user:42 | wc -c

A length shorter than expected indicates truncation.

Step 4: Confirm it is a real DUMP blob

Re-generate the payload immediately before restoring, in the same session, to rule out a stale or wrong blob.

Step 5: Read the logs

sudo journalctl -u redis-server --no-pager | grep -iE 'RESTORE|checksum|DUMP payload' | tail

Example Root Cause Analysis

A migration exports keys with redis-cli DUMP key into a JSON manifest, then a Python job reads that JSON and calls RESTORE. Every restore fails with DUMP payload version or checksum are wrong, even though source and destination are the same Redis version.

Length checks reveal the payloads in the manifest are a few bytes different from the source DUMP output. The cause is transport corruption: the binary DUMP bytes were stored as a UTF-8 JSON string, which silently altered non-UTF-8 bytes, so the CRC64 checksum no longer matched:

redis-cli -h SRC DUMP user:42 | wc -c    # 71 bytes
python3 -c "import json;print(len(json.load(open('m.json'))['user:42']))"   # 74 — mutated

The fix was to stop round-tripping the binary payload through JSON and instead pipe it byte-for-byte, using -x so redis-cli reads the raw blob from stdin:

redis-cli -h SRC DUMP user:42 | redis-cli -h DST -x RESTORE user:42 0 REPLACE   # OK

For the bulk job, payloads were base64-encoded in the manifest and decoded to exact bytes before RESTORE, which preserved the checksum. The migration then completed cleanly.

Prevention Best Practices

• Restore only into a Redis version equal to or newer than the one that produced the DUMP payload; never restore a newer RDB version into an older server.
• Treat DUMP output as opaque binary: pipe it byte-for-byte, or base64-encode it for any text channel — never store it in a UTF-8/JSON string directly.
• Use redis-cli -x RESTORE key ttl to read the raw payload from stdin instead of embedding it in shell arguments.
• Validate payload length end to end so truncation is caught before RESTORE.
• Prefer MIGRATE (which handles serialization internally) or native replication for large cross-instance moves instead of hand-rolled DUMP/RESTORE.
• Feed failed restores into the free incident assistant, and browse more Redis guides.

Quick Command Reference

# Compare versions (older target can't read newer payloads)
redis-cli -h SRC INFO server | grep redis_version
redis-cli -h DST INFO server | grep redis_version

# Byte-clean DUMP -> RESTORE (raw stdin, overwrite-safe)
redis-cli -h SRC DUMP user:42 | redis-cli -h DST -x RESTORE user:42 0 REPLACE

# Sanity-check payload length for truncation
redis-cli -h SRC DUMP user:42 | wc -c

# Prefer MIGRATE for cross-instance moves
redis-cli MIGRATE dst 6379 user:42 0 5000 COPY REPLACE

Conclusion

DUMP payload version or checksum are wrong means RESTORE rejected the blob because its RDB version is too new for the target or its CRC64 checksum no longer matches the bytes. The typical root causes are:

1. A payload produced by a newer Redis version than the target.
2. Binary-unsafe transport (shell quoting, JSON/UTF-8) mutating the bytes.
3. A truncated payload.
4. Passing something that isn’t a genuine DUMP output.

Keep the payload byte-identical from DUMP to RESTORE — pipe it raw with -x or base64-encode it for text channels — and restore only into an equal-or-newer Redis version. For large migrations, let MIGRATE or replication handle serialization instead of moving blobs by hand.