I build CacheDeck, an iPhone app for checking production Redis during an incident. Its key search had the bug this post measures, and version 1.4.9 fixes it. You won't need the app here: everything below runs in Docker with redis-cli.
I loaded 200,000 cache keys into a Redis container and hid 20 session:* keys among them. Then I asked SCAN for the sessions:
> SCAN 0 MATCH session:* COUNT 100 1) "79872" 2) (empty array) > SCAN 79872 MATCH session:* COUNT 100 1) "115200" 2) (empty array) > SCAN 115200 MATCH session:* COUNT 100 1) "173568" 2) (empty array) The full pass took 1,993 calls. Of those, 1,973 returned an empty array, and the pass found all 20 keys. A script that stops at the first empty page, or the sixteenth, reports that the keys don't exist.
My setup: the redis:8 image (Redis 8.10.3) in Docker on a Mac mini M4, runs on 18 and 20 November 2026.
An empty page means "call again"
SCAN walks the keyspace in slices. COUNT is a hint for the size of a slice, and the server uses 10 when you leave it out. Redis applies MATCH to a slice after it has read the keys, before it sends the reply. My 1,993 calls covered about 200,000 keys, so each call read about 100 keys and returned the ones that matched. With 20 sessions in the whole keyspace, most slices hold none.
The docs tell clients they "should not consider the iteration complete as long as the returned cursor is not zero".
The first match came anywhere from call 1 to call 383
For each of 20 runs I wrote 20 session keys with fresh random names next to the same 200,000 filler keys, then walked the keyspace with COUNT 100:
| 20 runs, 20 November | Range |
|---|---|
| Calls per full pass | 1,993 |
| Empty pages per pass | 1,973–1,974 |
| Call that returned the first match | 1 to 383 |
| Longest run of empty pages in a row | 249 to 766 |
In 20 more runs, in a different container on 18 November, the first match came between call 15 and call 585. With 200 sessions instead of 20, about 1,800 of 1,995 calls came back empty, and the first match arrived by call 19.
The chart shows the run with the latest first match:
COUNT trades round trips for blocking time
I added 20 hashes to the same keyspace and walked it three times at each of four COUNT values. I read the server-side cost from INFO commandstats and INFO latencystats:
COUNT | Calls per pass | Empty pages | Server time per call | p99 per call | Server time per pass |
|---|---|---|---|---|---|
| 10 (default) | 19,275 | 19,255 | 2.8–3.6 µs | 5–9 µs | 55–69 ms |
| 100 | 1,993 | 1,973 | 24–26 µs | 40–47 µs | 48–51 ms |
| 1,000 | 200 | 180 | 0.24–0.28 ms | 0.30–0.48 ms | 48–56 ms |
| 10,000 | 21 | 7 | 2.4–3.2 ms | 3.5–4.8 ms | 50–67 ms |
KEYS session:* | 1 | 26–29 ms | 26–29 ms |
Redis spends 50 to 70 ms on the whole pass at any COUNT. With COUNT you choose how Redis slices that time. Redis executes one command at a time, so a 2.5 ms SCAN call delays every command queued behind it by 2.5 ms. KEYS delays them by 26–29 ms in one piece.
The client pays per round trip. redis-cli --scan --pattern 'session:*' with its default COUNT of 10 made 19,275 calls and took 1.0–1.8 s on loopback, inside the container. With --count 1000 it made 200 calls in 77–93 ms. On a network with 20 ms round trips, 19,275 calls mean over six minutes of waiting, and 200 calls mean four seconds. I multiplied to get those two figures and ran no network test.
SCAN … TYPE returns the same run of empty pages. With 20 hashes among the 200,040 keys, SCAN 0 TYPE hash COUNT 100 and its follow-ups took 1,993 calls, and 1,973 came back empty. The docs say Redis applies the TYPE filter after reading the keys too, so it saves the server no work.
Reading a SCAN reply
| You see | What it means | Do next |
|---|---|---|
Empty array, cursor not 0 | no match in this slice | call again with the returned cursor |
Empty array, cursor 0 | the pass is complete, and this last slice had no match | stop and keep the matches from earlier pages; keys created during the pass may be missing |
| The same key twice | SCAN allows duplicates | deduplicate on the client |
| Rare pattern, large keyspace | most pages will come back empty | COUNT 1000 for this pass, or redis-cli --scan --count 1000 |
Redis Cluster 7.4 or later, a pattern with a hash tag such as user:{42}:* | Redis scans only that slot (7.4 release notes, #12536) | put hash tags in the key names you search by; I did not test this in cluster mode |
The bug I shipped
CacheDeck's search fetched pages of 100 keys until it found a match or hit 16 empty pages in a row. After the sixteenth it printed "No keys match. Nothing in db0 matches this pattern." The cursor was nonzero, and I had given the screen no button to continue. In 37 of my 40 runs the first match came after call 16, so the app would have reported nothing on a database that held the keys.
If you build a tool on SCAN, keep the cursor so the user can continue, and print "no matches" only when the cursor is back at 0 and no page returned a key.
Version 1.4.9, out since 18 November, prints "No keys match" only after the cursor returns to 0. Until then the key list and the search screen say "Only part of the database has been scanned.", and Load more continues from the saved cursor. A failed first SCAN used to end on "No keys match" as well; now you see the error and a Retry button. Filtering the key list by pattern is free, and the Search tab needs Pro. cachedeck.com
Tell me in the comments which COUNT your SCAN loop sends, and whether you chose it or kept the default of 10.
Redis is a registered trademark of Redis Ltd. CacheDeck is not affiliated with, endorsed by, or sponsored by Redis Ltd.


