references/kv/gotchas.md
KV Gotchas & Troubleshooting
Read the linked explanation before applying a workaround.
| Symptom or decision | Documentation and guidance |
|---------------------|----------------------------|
| Stale value after a write or delete | How KV works: allow for eventual consistency; neither local read-after-write visibility nor a fixed global propagation deadline is guaranteed. |
| Newly created key still appears absent | Read caching: missing-key lookups are cached too. Treat check-then-create as a race, not an atomic existence test. |
| Concurrent updates overwrite each other or writes are throttled | Concurrent writes: retries do not make read-modify-write atomic. Use coordination when correctness depends on ordering. |
| Missing-value errors | Read results: distinguish null from valid falsy values and distinguish absence from an operation failure. |
| Slow reads, large results, or excessive operations | Read guidance: select result types and bulk reads to match the workload; increasing read cache lifetime trades freshness for cache reuse. |
| Unexpected empty listing page | Pagination: use the completion flag and cursor, not page length, to determine whether to continue. |
| Data present in one environment but missing in another | KV bindings and environments: check local versus remote storage and the selected namespace. |
| Size, operation, or write-rate failures | Limits: retrieve current constraints before sizing values, batches, or retry policies. |
| Estimate costs or explain billing | Pricing: check allowances, billable operations, storage, and bulk accounting for the actual workload. |
Confirm freshness and failure requirements before adding a cache or a permissive fallback; see patterns.md.