1# Gotchas & Best Practices
2 
3## Common Errors
4 
5### "setState() not syncing"
6 
7**Cause:** Mutating state directly or not calling `setState()` after modifications  
8**Solution:** Always use `setState()` with immutable updates:
9```ts
10// ❌ this.state.count++
11// ✅ this.setState({...this.state, count: this.state.count + 1})
12```
13 
14### "Message history grows unbounded (AIChatAgent)"
15 
16**Cause:** `this.messages` in `AIChatAgent` accumulates all messages indefinitely  
17**Solution:** Manually trim old messages periodically:
18```ts
19export class ChatAgent extends AIChatAgent<Env> {
20  async onChatMessage(onFinish) {
21    // Keep only last 50 messages
22    if (this.messages.length > 50) {
23      this.messages = this.messages.slice(-50);
24    }
25    
26    return this.streamText({ model: openai("gpt-4"), messages: this.messages, onFinish });
27  }
28}
29```
30 
31### "SQL injection vulnerability"
32 
33**Cause:** Direct string interpolation in SQL queries
34**Solution:** Use parameterized queries:
35```ts
36// ❌ this.sql`...WHERE id = '${userId}'`
37// ✅ this.sql`...WHERE id = ${userId}`
38```
39 
40### "WebSocket connection timeout"
41 
42**Cause:** Not calling `conn.accept()` in `onConnect`
43**Solution:** Always accept connections:
44```ts
45async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: "123"}); }
46```
47 
48### "Schedule limit exceeded"
49 
50**Cause:** More than 1000 scheduled tasks per agent
51**Solution:** Clean up old schedules and limit creation rate:
52```ts
53async checkSchedules() { if ((await this.getSchedules()).length > 800) console.warn("Near limit!"); }
54```
55 
56### "AI Gateway unavailable"
57 
58**Cause:** AI service timeout or quota exceeded  
59**Solution:** Add error handling and fallbacks:
60```ts
61try { 
62  return await this.env.AI.run(model, {prompt}); 
63} catch (e) { 
64  console.error("AI error:", e);
65  return {error: "Unavailable"}; 
66}
67```
68 
69### "@callable method returns undefined"
70 
71**Cause:** Method doesn't return JSON-serializable value, or has non-serializable types  
72**Solution:** Ensure return values are plain objects/arrays/primitives:
73```ts
74// ❌ Returns class instance
75@callable()
76async getData() { return new Date(); }
77 
78// ✅ Returns serializable object
79@callable()
80async getData() { return { timestamp: Date.now() }; }
81```
82 
83### "Resumable stream not resuming"
84 
85**Cause:** Stream ID must be deterministic for resumption to work  
86**Solution:** Use AIChatAgent (automatic) or ensure consistent stream IDs:
87```ts
88// AIChatAgent handles this automatically
89export class ChatAgent extends AIChatAgent<Env> {
90  // Resumption works out of the box
91}
92```
93 
94### "MCP connection loss on hibernation"
95 
96**Cause:** MCP server connections don't survive hibernation  
97**Solution:** Re-register servers in `onStart()` or check connection status:
98```ts
99onStart() {
100  // Re-register MCP servers after hibernation
101  await this.mcp.registerServer("github", { url: env.MCP_URL, auth: {...} });
102}
103```
104 
105### "Agent not found"
106 
107**Cause:** Durable Object binding missing or incorrect class name  
108**Solution:** Verify DO binding in wrangler.jsonc and class name matches
109 
110## Rate Limits & Quotas
111 
112| Resource/Limit | Value | Notes |
113|----------------|-------|-------|
114| CPU per request | 30s (std), 300s (max) | Set in wrangler.jsonc |
115| Memory per instance | 128MB | Shared with WebSockets |
116| Storage per agent | 10GB | SQLite storage |
117| Scheduled tasks | 1000 per agent | Monitor with `getSchedules()` |
118| WebSocket connections | Unlimited | Within memory limits |
119| SQL columns | 100 | Per table |
120| SQL row size | 2MB | Key + value |
121| WebSocket message | 32MiB | Max size |
122| DO requests/sec | ~1000 | Per unique DO instance; rate limit if needed |
123| AI Gateway (Workers AI) | Model-specific | Check dashboard for limits |
124| MCP requests | Depends on server | Implement retry/backoff |
125 
126## Best Practices
127 
128### State Management
129- Use immutable updates: `setState({...this.state, key: newValue})`
130- Trim unbounded arrays (messages, logs) periodically
131- Store large data in SQL, not state
132 
133### SQL Usage
134- Create tables in `onStart()`, not `onRequest()`
135- Use parameterized queries: `` sql`WHERE id = ${id}` `` (NOT `` sql`WHERE id = '${id}'` ``)
136- Index frequently queried columns
137 
138### Scheduling
139- Monitor schedule count: `await this.getSchedules()`
140- Cancel completed tasks to stay under 1000 limit
141- Use cron strings for recurring tasks
142 
143### WebSockets
144- Always call `conn.accept()` in `onConnect()`
145- Handle client disconnects gracefully
146- Broadcast to `this.connections` efficiently
147 
148### AI Integration
149- Use `AIChatAgent` for chat interfaces (auto-streaming, resumption)
150- Trim message history to avoid token limits
151- Handle AI errors with try/catch and fallbacks
152 
153### Production Deployment
154- **Rate limiting:** Implement request throttling for high-traffic agents (>1000 req/s)
155- **Monitoring:** Log critical errors, track schedule count, monitor storage usage
156- **Graceful degradation:** Handle AI service outages with fallbacks
157- **Message trimming:** Enforce max history length (e.g., 100 messages) in AIChatAgent
158- **MCP reliability:** Re-register servers on hibernation, implement retry logic
159