Your Anthropic prompt cache never registers a read — how do you debug it?

## Start from the counters, not the code Prompt caching never throws. A misplaced or ineffective `cache_control` produces a perfectly normal response, so the only evidence is the `usage` object. Two distinct symptoms point at two different families of cause: - **Creation is always zero.** Nothing is being cached at all. The prefix is too small, or the marker is not where you think it is. - **Creation is non-zero every call, read is always zero.** Caching works, but no two requests share a prefix, or the entry dies before the next request arrives. ## Symptom 1: nothing is cached The most common cause is the **minimum cacheable prefix size**. Prefixes shorter than the threshold are not stored, and the API does not complain. The threshold depends on the model class — around 1024 tokens for Sonnet- and Opus-class models and around 2048 for the smaller Haiku class — so the same prompt can cache on one model and silently not on another. Count the tokens in your prefix before assuming a bug. The second cause is placement: the block you decorated is not actually inside the prefix you think, for example a `cache_control` on a message that sits after the content you wanted covered. Since the marker ends the prefix rather than selecting content, a marker placed too early caches far less than intended. ## Symptom 2: written every time, never read Now you are hunting variability ahead of the breakpoint, because matching is exact. **Injected dynamic text.** "Current date: …", a session or request ID, a user's name, an A/B flag, a random few-shot sample. Anything templated into the system prompt is suspect. **Unstable serialization.** Tool definitions built from a dict or set can serialize with different key or member ordering between processes. So can a JSON Schema assembled by reflection. The bytes must be identical, not merely equivalent. **A changed tool list.** Tools sit at the very front of the prefix, so adding, removing or reordering one invalidates everything behind it — including a system prompt you never touched. **Model or configuration drift.** Cache entries are keyed per model, so a routing layer that spreads traffic across model versions gives each its own entry. Toggling features that change how the prompt is assembled has the same effect. **Expiry.** The default window is about five minutes and refreshes on each hit. Low-QPS services with multi-minute gaps write and never read. Either raise the TTL to the one-hour tier or accept that caching does not pay here. **Cold-start concurrency.** An entry is not available for reads until the first request that writes it has processed the prefix. Deploying ten workers that all fire simultaneously produces ten writes and zero reads. Warm the cache with one request, then fan out. ## Reproducing it cleanly Reduce to a two-call script against a static prefix with no templating at all. Print `usage` from both calls. If call two reads, your production prefix is the variable; diff the serialized requests byte for byte — not the objects, the actual JSON — and the culprit usually appears immediately. If call two still writes, the prefix is too short or the marker is misplaced. ## Making it not recur Build the cached prefix once, in one place, from constants, and assert its stability: hash the serialized prefix and log the hash with the request. A hash that varies across requests that should share a cache is a one-line alarm, and it catches the failure the day someone adds a personalization field, rather than at the end of the billing month. Pair it with a hit-rate metric derived from the two usage counters per route, and both silent failure modes become visible.