1# Binding Gotchas and Troubleshooting
2 
3## Critical: Global Scope Mutation
4 
5### ❌ THE #1 GOTCHA: Caching env in Global Scope
6 
7```typescript
8// ❌ DANGEROUS - env cached at deploy time
9const apiKey = env.API_KEY;  // ERROR: env not available in global scope
10 
11export default {
12  async fetch(request: Request, env: Env) {
13    // Uses undefined or stale value!
14  }
15}
16```
17 
18**Why it breaks:**
19- `env` not available in global scope
20- If using workarounds, secrets may not update without redeployment
21- Leads to "Cannot read property 'X' of undefined" errors
22 
23**✅ Always access env per-request:**
24```typescript
25export default {
26  async fetch(request: Request, env: Env) {
27    const apiKey = env.API_KEY;  // Fresh every request
28  }
29}
30```
31 
32## Common Errors
33 
34### "env.MY_KV is undefined"
35 
36**Cause:** Name mismatch or not configured  
37**Solution:** Check wrangler.jsonc (case-sensitive), run `npx wrangler types`, verify `npx wrangler kv namespace list`
38 
39### "Property 'MY_KV' does not exist on type 'Env'"
40 
41**Cause:** Types not generated  
42**Solution:** `npx wrangler types`
43 
44### "preview_id is required for --remote"
45 
46**Cause:** Missing preview binding  
47**Solution:** Add `"preview_id": "dev-id"` or use `npx wrangler dev` (local mode)
48 
49### "Secret updated but Worker still uses old value"
50 
51**Cause:** Cached in global scope or not redeployed  
52**Solution:** Avoid global caching, redeploy after secret change
53 
54### "KV get() returns null for existing key"
55 
56**Cause:** Eventual consistency (60s), wrong namespace, wrong environment  
57**Solution:**
58```bash
59# Check key exists
60npx wrangler kv key get --binding=MY_KV "your-key"
61 
62# Verify namespace ID
63npx wrangler kv namespace list
64 
65# Check environment
66npx wrangler deployments list
67```
68 
69### "D1 database not found"
70 
71**Solution:** `npx wrangler d1 list`, verify ID in wrangler.jsonc
72 
73### "Service binding returns 'No such service'"
74 
75**Cause:** Target Worker not deployed, name mismatch, environment mismatch  
76**Solution:**
77```bash
78# List deployed Workers
79npx wrangler deployments list --name=target-worker
80 
81# Check service binding config
82cat wrangler.jsonc | grep -A2 services
83 
84# Deploy target first
85cd ../target-worker && npx wrangler deploy
86```
87 
88### "Rate limit exceeded" on KV writes
89 
90**Cause:** >1 write/second per key  
91**Solution:** Use different keys, Durable Objects, or Queues
92 
93## Type Safety Gotchas
94 
95### Missing @cloudflare/workers-types
96 
97**Error:** `Cannot find name 'Request'`  
98**Solution:** `npm install -D @cloudflare/workers-types`, add to tsconfig.json `"types"`
99 
100### Binding Type Mismatches
101 
102```typescript
103// ❌ Wrong - KV returns string | null
104const value: string = await env.MY_KV.get('key');
105 
106// ✅ Handle null
107const value = await env.MY_KV.get('key');
108if (!value) return new Response('Not found', { status: 404 });
109```
110 
111## Environment Gotchas
112 
113### Wrong Environment Deployed
114 
115**Solution:** Check `npx wrangler deployments list`, use `--env` flag
116 
117### Secrets Not Per-Environment
118 
119**Solution:** Set per environment: `npx wrangler secret put API_KEY --env staging`
120 
121## Development Gotchas
122 
123**wrangler dev vs deploy:**
124- dev: Uses `preview_id` or local bindings, secrets not available
125- deploy: Uses production `id`, secrets available
126 
127**Access secrets in dev:** `npx wrangler dev --remote`  
128**Persist local data:** `npx wrangler dev --persist`
129 
130## Performance Gotchas
131 
132### Sequential Binding Calls
133 
134```typescript
135// ❌ Slow
136const user = await env.DB.prepare('...').first();
137const config = await env.MY_KV.get('config');
138 
139// ✅ Parallel
140const [user, config] = await Promise.all([
141  env.DB.prepare('...').first(),
142  env.MY_KV.get('config')
143]);
144```
145 
146## Security Gotchas
147 
148**❌ Secrets in logs:** `console.log('Key:', env.API_KEY)` - visible in dashboard  
149**✅** `console.log('Key:', env.API_KEY ? '***' : 'missing')`
150 
151**❌ Exposing env:** `return Response.json(env)` - exposes all bindings  
152**✅** Never return env object in responses
153 
154## Limits Reference
155 
156| Resource | Limit | Impact | Plan |
157|----------|-------|--------|------|
158| **Bindings per Worker** | 64 total | All binding types combined | All |
159| **Environment variables** | 64 max, 5KB each | Per Worker | All |
160| **Secret size** | 1KB | Per secret | All |
161| **KV key size** | 512 bytes | UTF-8 encoded | All |
162| **KV value size** | 25 MB | Per value | All |
163| **KV writes per key** | 1/second | Per key; exceeding = 429 error | All |
164| **KV list() results** | 1000 keys | Per call; use cursor for more | All |
165| **KV operations** | 1000 reads/day | Free tier only | Free |
166| **R2 object size** | 5 TB | Per object | All |
167| **R2 operations** | 1M Class A/month free | Writes | All |
168| **D1 database size** | 10 GB | Per database | All |
169| **D1 rows per query** | 100,000 | Result set limit | All |
170| **D1 databases** | 10 | Free tier | Free |
171| **Queue batch size** | 100 messages | Per consumer batch | All |
172| **Queue message size** | 128 KB | Per message | All |
173| **Service binding calls** | Unlimited | Counts toward CPU time | All |
174| **Durable Objects** | 1M requests/month free | First 1M | Free |
175 
176## Debugging Tips
177 
178```bash
179# Check configuration
180npx wrangler deploy --dry-run       # Validate config without deploying
181npx wrangler kv namespace list      # List KV namespaces
182npx wrangler secret list            # List secrets (not values)
183npx wrangler deployments list       # Recent deployments
184 
185# Inspect bindings
186npx wrangler kv key list --binding=MY_KV
187npx wrangler kv key get --binding=MY_KV "key-name"
188npx wrangler r2 object get my-bucket/file.txt
189npx wrangler d1 execute my-db --command="SELECT * FROM sqlite_master"
190 
191# Test locally
192npx wrangler dev                  # Local mode
193npx wrangler dev --remote         # Production bindings
194npx wrangler dev --persist        # Persist data across restarts
195 
196# Verify types
197npx wrangler types
198cat .wrangler/types/runtime.d.ts | grep "interface Env"
199 
200# Debug specific binding issues
201npx wrangler tail                 # Stream logs in real-time
202npx wrangler tail --format=pretty # Formatted logs
203```
204 
205## See Also
206 
207- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/)
208- [Wrangler Commands](https://developers.cloudflare.com/workers/wrangler/commands/)
209