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:

Step chart of keys found during one SCAN pass with COUNT 100 over 200,020 keys. The line stays at zero until call 383, then climbs to 20 keys by call 1,981. The pass ends at call 1,993. A marker at call 16 shows that a 16-page budget would have stopped with zero keys found.

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.