Why KEYS Can Crash Redis and How SCAN Keeps It Responsive

Preface

Sometimes we need to inspect the usage of Redis keys with a specific prefix in a production environment.

Incident

Our user‑token cache stores values under keys like user_token:userid. To help developers see how many users are logged in, operations ran keys user_token*, which caused Redis to become unresponsive.

Root Cause Analysis

With several million login keys, the KEYS command performs a full O(n) traversal of the dictionary. Because Redis processes commands in a single thread, the KEYS operation blocks all other commands, leading to a “dead” Redis instance.

Solution

Replace KEYS with the incremental SCAN command. Although SCAN also has O(n) complexity, it returns results in small batches using a cursor, so it does not block the server thread.

1. Complexity remains O(n) but is cursor‑based and non‑blocking. 2. The optional COUNT argument specifies how many slots to examine per iteration (it is not a limit on result count). 3. Like KEYS, SCAN supports pattern matching. 4. The server does not keep cursor state; the client holds the cursor integer returned by SCAN. 5. Results may contain duplicates; the client must deduplicate. 6. An empty result set does not mean the scan is finished; the cursor value must be zero to indicate completion.

Command format: SCAN cursor [MATCH pattern] [COUNT count] Explanation: MATCH filters keys by pattern, and COUNT hints how many elements to return per call.

Example:

redis> scan 0 match user_token* count 5
1) "6"
2) "user_token:1000"
3) "user_token:1001"
4) "user_token:1010"
5) "user_token:2300"
6) "user_token:1389"

The cursor returned (6) is used for the next call:

redis> scan 6 match user_token* count 5
1) "10"
2) "user_token:3100"
3) "user_token:1201"
4) "user_token:1410"
5) "user_token:5300"
6) "user_token:3389"

Summary

SCAN is a frequent interview question and a practical technique for safely iterating over large Redis keyspaces without causing service disruption.