1# Workers Gotchas
2 
3## Common Errors
4 
5### "Too much CPU time used"
6 
7**Cause:** Worker exceeded CPU time limit (10ms on Free plan, 30s default / 5min max on Paid)  
8**Solution:** Use `ctx.waitUntil()` for background work, offload heavy compute to Durable Objects, or consider Workers AI for ML workloads
9 
10### "Module-Level State Lost"
11 
12**Cause:** Workers are stateless between requests; module-level variables reset unpredictably  
13**Solution:** Use KV, D1, or Durable Objects for persistent state; don't rely on module-level variables
14 
15### "Body has already been used"
16 
17**Cause:** Attempting to read response body twice (bodies are streams)  
18**Solution:** Clone response before reading: `response.clone()` or read once and create new Response with the text
19 
20### "Node.js module not found"
21 
22**Cause:** Node.js built-ins not available by default  
23**Solution:** Use Workers APIs (e.g., R2 for file storage) or enable Node.js compat with `"compatibility_flags": ["nodejs_compat"]`
24 
25### "Cannot fetch in global scope"
26 
27**Cause:** Attempting to use fetch during module initialization  
28**Solution:** Move fetch calls inside handler functions (fetch, scheduled, etc.) where they're allowed
29 
30### "Subrequest depth limit exceeded"
31 
32**Cause:** Too many nested subrequests creating deep call chain  
33**Solution:** Flatten request chain or use service bindings for direct Worker-to-Worker communication
34 
35### "D1 read-after-write inconsistency"
36 
37**Cause:** D1 is eventually consistent; reads may not reflect recent writes  
38**Solution:** Use D1 Sessions (2024+) to guarantee read-after-write consistency within a session:
39 
40```typescript
41const session = env.DB.withSession();
42await session.prepare('INSERT INTO users (name) VALUES (?)').bind('Alice').run();
43const user = await session.prepare('SELECT * FROM users WHERE name = ?').bind('Alice').first(); // Guaranteed to see Alice
44```
45 
46**When to use sessions:** Write → Read patterns, transactions requiring consistency
47 
48### "wrangler types not generating TypeScript definitions"
49 
50**Cause:** Type generation not configured or outdated  
51**Solution:** Run `npx wrangler types` after changing bindings in wrangler.jsonc:
52 
53```bash
54npx wrangler types  # Generates .wrangler/types/runtime.d.ts
55```
56 
57Add to `tsconfig.json`: `"include": [".wrangler/types/**/*.ts"]`
58 
59Then import: `import type { Env } from './.wrangler/types/runtime';`
60 
61### "Durable Object RPC errors with deprecated fetch pattern"
62 
63**Cause:** Using old `stub.fetch()` pattern instead of RPC (2024+)  
64**Solution:** Export methods directly, call via RPC:
65 
66```typescript
67// ❌ Old fetch pattern
68export class MyDO {
69  async fetch(request: Request) {
70    const { method } = await request.json();
71    if (method === 'increment') return new Response(String(await this.increment()));
72  }
73  async increment() { return ++this.value; }
74}
75const stub = env.DO.get(id);
76const res = await stub.fetch('http://x', { method: 'POST', body: JSON.stringify({ method: 'increment' }) });
77 
78// ✅ RPC pattern (type-safe, no serialization overhead)
79export class MyDO {
80  async increment() { return ++this.value; }
81}
82const stub = env.DO.get(id);
83const count = await stub.increment(); // Direct method call
84```
85 
86### "WebSocket connection closes unexpectedly"
87 
88**Cause:** Worker reaches CPU limit while maintaining WebSocket connection  
89**Solution:** Use WebSocket hibernation (2024+) to offload idle connections:
90 
91```typescript
92export class WebSocketDO {
93  async webSocketMessage(ws: WebSocket, message: string) {
94    // Handle message
95  }
96  async webSocketClose(ws: WebSocket, code: number) {
97    // Cleanup
98  }
99}
100```
101 
102Hibernation automatically suspends inactive connections, wakes on events
103 
104### "Framework middleware not working with Workers"
105 
106**Cause:** Framework expects Node.js primitives (e.g., Express uses Node streams)  
107**Solution:** Use Workers-native frameworks (Hono, itty-router, Worktop) or adapt middleware:
108 
109```typescript
110// ✅ Hono (Workers-native)
111import { Hono } from 'hono';
112const app = new Hono();
113app.use('*', async (c, next) => { /* middleware */ await next(); });
114```
115 
116See [frameworks.md](./frameworks.md) for full patterns
117 
118## Limits
119 
120| Limit | Value | Notes |
121|-------|-------|-------|
122| Request size | 100 MB | Maximum incoming request size |
123| Response size | Unlimited | Supports streaming |
124| CPU time (Free) | 10ms | Free plan |
125| CPU time (Paid) | 30s default / 5min max | Configurable via `limits.cpu_ms` |
126| Subrequests (Free) | 50 | Per invocation |
127| Subrequests (Paid) | 10,000 | Per invocation |
128| Subrequest operations (KV, R2, Cache API) | 1,000 | Shared across KV reads, R2 ops, Cache API calls per request |
129| KV value size | 25 MiB | Maximum per key |
130| Environment variable size | 5 KB | Per variable |
131 
132## See Also
133 
134- [Patterns](./patterns.md) - Best practices
135- [API](./api.md) - Runtime APIs
136- [Configuration](./configuration.md) - Setup
137- [Frameworks](./frameworks.md) - Hono, routing, validation
138