阅读中文版本

Redis WRONGTYPE Operation — Key Holds a Different Type

Fix Redis WRONGTYPE by inspecting the key type, using matching commands, and namespacing keys by data structure.

redis-cli TYPE cache:user:1

redis-cli SET k v; redis-cli HSET k f v

Symptoms

This debugging guide addresses “Redis WRONGTYPE Operation — Key Holds a Different Type”. Start from the symptoms, follow the ordered diagnostics, and confirm each hypothesis before moving on; the fix and verification steps then close the loop.

Observed symptoms include:

• WRONGTYPE Operation against a key holding the wrong kind of value
• A command works for new keys but fails for an existing key
• The error appears after a deploy changed how a key is stored

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Check the actual key type

redis-cli TYPE cache:user:1

The returned type (string, hash, list, set, zset) tells you which commands are valid.

Step 2: Reproduce the mismatch

redis-cli SET k v; redis-cli HSET k f v

The second command fails with WRONGTYPE, proving the key is a string, not a hash.

Likely contributors, in order of frequency:

• A string key is then used with hash or list commands (or vice versa)
• Key naming collides across features that store different structures
• An old key retains its previous type after a code change

Root Cause

Redis keys have exactly one type, set on first write. Using a command for a different type raises WRONGTYPE, which often reveals key-name collisions or a storage-format change between deployments.

The Fix

Use commands matching the key type, namespace keys by structure (user:1:profile hash versus user:1:token string), and migrate or delete stale keys when the format changes.

Watch out: DEL on a wrong-type key destroys data; confirm the key is safe to remove before deleting during migration.

# inspect before operating
redis-cli TYPE user:1:profile      # -> hash
redis-cli HGETALL user:1:profile

# namespace by structure to avoid collisions
redis-cli HSET user:1:profile name alice
redis-cli SET  user:1:token  abc123   # different key, string type

# migrate by writing the new type under the right key, then delete the old

Verify and Prevent

Rerun the command with the correct type and confirm it succeeds; verify TYPE reports the expected structure.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.