1# KV Gotchas & Troubleshooting
2 
3## Common Errors
4 
5### "Stale Read After Write"
6 
7**Cause:** Eventual consistency means writes may not be immediately visible in other regions  
8**Solution:** Don't read immediately after write; return confirmation without reading or use the local value you just wrote. Writes visible immediately in same location, ≤60s globally
9 
10```typescript
11// ❌ BAD: Read immediately after write
12await env.KV.put("key", "value");
13const value = await env.KV.get("key"); // May be null in other regions!
14 
15// ✅ GOOD: Use the value you just wrote
16const newValue = "value";
17await env.KV.put("key", newValue);
18return new Response(newValue); // Don't re-read
19```
20 
21### "429 Rate Limit on Concurrent Writes"
22 
23**Cause:** Multiple concurrent writes to same key exceeding 1 write/second limit  
24**Solution:** Use sequential writes, unique keys for concurrent operations, or implement retry with exponential backoff
25 
26```typescript
27async function putWithRetry(
28  kv: KVNamespace,
29  key: string,
30  value: string,
31  maxAttempts = 5
32): Promise<void> {
33  let delay = 1000;
34  for (let i = 0; i < maxAttempts; i++) {
35    try {
36      await kv.put(key, value);
37      return;
38    } catch (err) {
39      if (err instanceof Error && err.message.includes("429")) {
40        if (i === maxAttempts - 1) throw err;
41        await new Promise(r => setTimeout(r, delay));
42        delay *= 2; // Exponential backoff
43      } else {
44        throw err;
45      }
46    }
47  }
48}
49```
50 
51### "Inefficient Multiple Gets"
52 
53**Cause:** Making multiple individual get() calls instead of bulk operation  
54**Solution:** Use bulk get with array of keys: `env.USERS.get(["user:1", "user:2", "user:3"])` to reduce to 1 operation
55 
56### "Null Reference Error"
57 
58**Cause:** Attempting to use value without checking for null when key doesn't exist  
59**Solution:** Always handle null returns - KV returns `null` for missing keys, not undefined
60 
61```typescript
62// ❌ BAD: Assumes value exists
63const config = await env.KV.get("config", "json");
64return config.theme; // TypeError if null!
65 
66// ✅ GOOD: Null checks
67const config = await env.KV.get("config", "json");
68return config?.theme ?? "default";
69 
70// ✅ GOOD: Early return
71const config = await env.KV.get("config", "json");
72if (!config) return new Response("Not found", { status: 404 });
73return new Response(config.theme);
74```
75 
76### "Negative Lookup Caching"
77 
78**Cause:** Keys that don't exist are cached as "not found" for up to 60s  
79**Solution:** Creating a key after checking won't be visible until cache expires
80 
81```typescript
82// Check → create pattern has race condition
83const exists = await env.KV.get("key"); // null, cached as "not found"
84if (!exists) {
85  await env.KV.put("key", "value");
86  // Next get() may still return null for ~60s due to negative cache
87}
88 
89// Alternative: Always assume key may not exist, use defaults
90const value = await env.KV.get("key") ?? "default-value";
91```
92 
93## Performance Tips
94 
95| Scenario | Recommendation | Why |
96|----------|----------------|-----|
97| Large values (>1MB) | Use `stream` type | Avoids buffering entire value in memory |
98| Many small keys | Coalesce into one JSON object | Reduces operations, improves cache hit rate |
99| High write volume | Spread across different keys | Avoid 1 write/second per-key limit |
100| Cold reads | Increase `cacheTtl` parameter | Reduces latency for frequently-read data |
101| Bulk operations | Use array form of get() | Single operation, better performance |
102 
103## Cost Examples
104 
105**Free tier:**
106- 100K reads/day = 3M/month ✅
107- 1K writes/day = 30K/month ✅
108- 1GB storage ✅
109 
110**Example paid workload:**
111- 10M reads/month = $5.00
112- 100K writes/month = $0.50
113- 1GB storage = $0.50
114- **Total: ~$6/month**
115 
116## Limits
117 
118| Limit | Value | Notes |
119|-------|-------|-------|
120| Key size | 512 bytes | Maximum key length |
121| Value size | 25 MiB | Maximum value; 413 error if exceeded |
122| Metadata size | 1024 bytes | Maximum metadata per key |
123| cacheTtl minimum | 60s | Minimum cache TTL |
124| Write rate per key | 1 write/second | All plans; 429 error if exceeded |
125| Propagation time | ≤60s | Global propagation time |
126| Bulk get max | 100 keys | Maximum keys per bulk operation |
127| Operations per Worker | 1,000 | Per request (bulk counts as 1) |
128| Reads pricing | $0.50 per 1M | Per million reads |
129| Writes pricing | $5.00 per 1M | Per million writes |
130| Deletes pricing | $5.00 per 1M | Per million deletes |
131| Storage pricing | $0.50 per GB-month | Per GB per month |
132