Redis big keys are single keys that hold far more data than the rest: a hash with millions of fields, a list used as an unbounded queue, a sorted set leaderboard nobody ever trims, a multi-megabyte JSON string. Redis executes commands on one main thread, so one operation that touches the whole key, including deleting it, holds every other client until it finishes.
Why one key can hurt everything
- Latency.
HGETALL,LRANGE 0 -1,SMEMBERSorZRANGEover the whole key are O(N). On a key with millions of elements that is milliseconds to seconds of a blocked server, and it shows up as random timeouts in unrelated parts of the application. We cover the diagnosis side in Redis latency spikes and SLOWLOG. - Deletion. The Redis config is explicit:
DELis a blocking deletion, and for an aggregated value with millions of elements the server can block for a long time, even seconds (redis.conf, LAZY FREEING). Expiry and eviction of such a key free memory the same way unless lazy freeing is enabled. - Network. Reading a 50 MB value moves 50 MB to the client and fills its output buffer on the server side.
- Memory surprises. One key growing quietly is the most common reason for an "unexplained" climb toward
maxmemory, see Redis OOM and eviction policies.
Finding big keys without hurting production
# biggest keys by element count, per type (uses SCAN)
redis-cli -h replica1 --bigkeys -i 0.1
# biggest keys by memory
redis-cli -h replica1 --memkeys
# both, with a top-N list and size distribution (newer redis-cli)
redis-cli -h replica1 --keystats --top 20
# only one key prefix
redis-cli -h replica1 --memkeys --pattern 'session:*'
--bigkeyslooks for keys with many elements and reports the biggest key per type plus a summary.--memkeysdoes the same by memory.--keystatscombines both and adds a top-N list (--top, default 10) and a size distribution (redis-cli docs).- All of them walk the keyspace with
SCAN, notKEYS, so they can run against a busy server.-i 0.1sleeps 0.1 seconds per 100 SCAN calls if you want to make the load negligible. - The docs note these modes now also work on cluster replicas. Running them on a replica keeps even the small extra load off the primary.
--bigkeysmeasures element count, not bytes. A hash with 200 fields of 1 MB each is "small" by count and huge by memory, which is why you want--memkeysor--keystatstoo.- With
--keystats,--cursorresumes an interrupted scan, which is useful on very large keyspaces.
Measuring one key
MEMORY USAGE cart:91823 # estimate, samples 5 nested values
MEMORY USAGE cart:91823 SAMPLES 0 # exact, walks every element (slow on huge keys)
TYPE cart:91823
HLEN cart:91823 # or LLEN / SCARD / ZCARD / XLEN / STRLEN
OBJECT ENCODING cart:91823
MEMORY USAGE reports the bytes a key and its value need in RAM, including administrative overhead. For nested types it samples 5 nested values by default and extrapolates; SAMPLES 0 samples all of them (MEMORY USAGE). Sampling everything is exact but O(N), so on a ten-million-element key it is itself a slow command. Use the default for discovery and the full count only when you need the real number, ideally on a replica.
Deleting a big key without blocking
# frees memory in a background thread instead of blocking
UNLINK feed:global
# or make DEL behave like UNLINK (Redis default: no)
CONFIG SET lazyfree-lazy-user-del yes
# trim a huge hash gradually instead of deleting it at once
redis-cli --no-raw HSCAN big:hash 0 COUNT 500
# ... HDEL big:hash field1 field2 ... field500, repeat with the next cursor
UNLINKremoves the key from the keyspace in O(1) and reclaims the memory in a different thread, so it does not block likeDEL(UNLINK). It has been available since Redis 4.0.- In Redis, all lazy-freeing options default to
no:lazyfree-lazy-eviction,lazyfree-lazy-expire,lazyfree-lazy-server-del,replica-lazy-flush,lazyfree-lazy-user-delandlazyfree-lazy-user-flush. Valkey's default configuration ships them asyes. Check what your version actually runs withCONFIG GET lazyfree*. - Enabling
lazyfree-lazy-expireandlazyfree-lazy-evictionmatters if big keys have a TTL or can be evicted: otherwise the main thread frees them when they expire or get evicted, at a moment you did not choose. - If you need to shrink a key rather than drop it, iterate with
HSCAN,SSCANorZSCANand delete in small batches, or useLTRIMfor lists.
KEYS * blocks the server for the whole keyspace, and "just checking" a suspicious key with HGETALL is exactly the slow command you are trying to find. Count first (HLEN, LLEN, SCARD, ZCARD), measure second.Stopping them from coming back
- Bound every collection in code:
LTRIMafterLPUSH,ZREMRANGEBYRANKfor leaderboards,XADD ... MAXLEN ~for streams. - Split by a natural key:
cart:{user}instead of onecartshash, daily buckets instead of one forever-growing set. - Put large blobs somewhere else (object storage, a database) and keep a reference in Redis.
- Run
--memkeysor--keystatson a replica on a schedule and alert when the top key crosses a size you agreed on. In our experience a weekly scan catches most offenders before they become an incident.
On large datasets and clusters
On a test instance with a few thousand keys, nothing here is noticeable. At tens of gigabytes and hundreds of thousands of operations per second, big keys change how the whole system behaves:
- A cluster cannot split a key. Each key lives in one hash slot on one shard. A 10 GB hash makes that shard bigger and hotter than the others, and adding nodes does not help, because resharding moves slots, not parts of a key. In our experience moving a slot that contains a very large key during resharding is also where migrations stall.
- Replication buffers. Writes to big keys and their deletions are replicated to every replica. The default output buffer limit for replica clients is
256mbhard,64mbsoft for 60 seconds; a burst of large writes that exceeds it disconnects the replica, which then needs a resync. With very large datasets that resync is expensive, and it can repeat. - Scans take hours. A full
--memkeysover hundreds of millions of keys takes a long time. Use--patternfor suspect prefixes, throttle with-i, and with--keystatsresume from--cursorinstead of restarting. - Cleanup is a project. Deleting one big key with
UNLINKis easy. Deleting millions of medium keys found by a pattern should be done in batches from a replica-generated list, withUNLINK, while watching latency and replication lag. - Single values have a ceiling. A single string or bulk argument is limited by
proto-max-bulk-len, 512 MB by default. Getting anywhere near it means the data model is wrong.
Key takeaways
- Big keys block Redis's main thread on full reads,
DEL, expiry and eviction, and cause latency spikes for unrelated clients. - Find them with
redis-cli --bigkeys(element count),--memkeys(bytes) or--keystats, run on a replica and throttled with-i. MEMORY USAGEsamples 5 nested values by default;SAMPLES 0is exact but O(N).- Delete with
UNLINK; Redis lazyfree options default tono, Valkey's default config sets them toyes. - In clusters a big key pins one shard and cannot be split by resharding; fix the data model, not the cluster size.
- Bound collections in code and scan the keyspace regularly so big keys are caught before they cause an incident.