1## Critical Gotchas
2 
3### ⚠️ WebSocket: fetch() vs containerFetch()
4 
5**Problem:** WebSocket connections fail silently
6 
7**Cause:** `containerFetch()` doesn't support WebSocket upgrades
8 
9**Fix:** Always use `fetch()` for WebSocket
10 
11```typescript
12// ❌ WRONG
13return container.containerFetch(request);
14 
15// ✅ CORRECT
16return container.fetch(request);
17```
18 
19### ⚠️ startAndWaitForPorts() vs start()
20 
21**Problem:** "connection refused" after `start()`
22 
23**Cause:** `start()` returns when process starts, NOT when ports ready
24 
25**Fix:** Use `startAndWaitForPorts()` before requests
26 
27```typescript
28// ❌ WRONG
29await container.start();
30return container.fetch(request);
31 
32// ✅ CORRECT
33await container.startAndWaitForPorts();
34return container.fetch(request);
35```
36 
37### ⚠️ Activity Timeout on Long Operations
38 
39**Problem:** Container stops during long work
40 
41**Cause:** `sleepAfter` based on request activity, not internal work
42 
43**Fix:** Renew timeout by touching storage
44 
45```typescript
46const interval = setInterval(() => {
47  this.ctx.storage.put("keepalive", Date.now());
48}, 60000);
49 
50try {
51  await this.doLongWork(data);
52} finally {
53  clearInterval(interval);
54}
55```
56 
57### ⚠️ blockConcurrencyWhile for Startup
58 
59**Problem:** Race conditions during initialization
60 
61**Fix:** Use `blockConcurrencyWhile` for atomic initialization
62 
63```typescript
64await this.ctx.blockConcurrencyWhile(async () => {
65  if (!this.initialized) {
66    await this.startAndWaitForPorts();
67    this.initialized = true;
68  }
69});
70```
71 
72### ⚠️ Lifecycle Hooks Block Requests
73 
74**Problem:** Container unresponsive during `onStart()`
75 
76**Cause:** Hooks run in `blockConcurrencyWhile` - no concurrent requests
77 
78**Fix:** Keep hooks fast, avoid long operations
79 
80### ⚠️ Don't Override alarm() When Using schedule()
81 
82**Problem:** Scheduled tasks don't execute
83 
84**Cause:** `schedule()` uses `alarm()` internally
85 
86**Fix:** Implement `alarm()` to handle scheduled tasks
87 
88## Common Errors
89 
90### "Container start timeout"
91 
92**Cause:** Container took >8s (`start()`) or >20s (`startAndWaitForPorts()`)
93 
94**Solutions:**
95- Optimize image (smaller base, fewer layers)
96- Check `entrypoint` correct
97- Verify app listens on correct ports
98- Increase timeout if needed
99 
100### "Port not available"
101 
102**Cause:** Calling `fetch()` before port ready
103 
104**Solution:** Use `startAndWaitForPorts()`
105 
106### "Container memory exceeded"
107 
108**Cause:** Using more memory than instance type allows
109 
110**Solutions:**
111- Use larger instance type (standard-2, standard-3, standard-4)
112- Optimize app memory usage
113- Use custom instance type
114 
115```jsonc
116"instance_type_custom": {
117  "vcpu": 2,
118  "memory_mib": 8192
119}
120```
121 
122### "Max instances reached"
123 
124**Cause:** All `max_instances` slots in use
125 
126**Solutions:**
127- Increase `max_instances`
128- Implement proper `sleepAfter`
129- Use `getRandom()` for distribution
130- Check for instance leaks
131 
132### "No container instance available"
133 
134**Cause:** Account capacity limits reached
135 
136**Solutions:**
137- Check account limits
138- Review instance types across containers
139- Contact Cloudflare support
140 
141## Limits
142 
143| Resource | Limit | Notes |
144|----------|-------|-------|
145| Cold start | 2-3s | Image pre-fetched globally |
146| Graceful shutdown | 15 min | SIGTERM → SIGKILL |
147| `start()` timeout | 8s | Process start |
148| `startAndWaitForPorts()` timeout | 20s | Port ready |
149| Max vCPU per container | 4 | standard-4 or custom |
150| Max memory per container | 12 GiB | standard-4 or custom |
151| Max disk per container | 20 GB | Ephemeral, resets |
152| Account total memory | 400 GiB | All containers |
153| Account total vCPU | 100 | All containers |
154| Account total disk | 2 TB | All containers |
155| Image storage | 50 GB | Per account |
156| Disk persistence | None | Use DO storage |
157 
158## Best Practices
159 
1601. **Use `startAndWaitForPorts()` by default** - Prevents port errors
1612. **Set appropriate `sleepAfter`** - Balance resources vs cold starts
1623. **Use `fetch()` for WebSocket** - Not `containerFetch()`
1634. **Design for restarts** - Ephemeral disk, implement graceful shutdown
1645. **Monitor resources** - Stay within account limits
1656. **Keep hooks fast** - Run in `blockConcurrencyWhile`
1667. **Renew activity for long ops** - Touch storage to prevent timeout
167 
168## Beta Caveats
169 
170⚠️ Containers in **beta**:
171 
172- **API may change** without notice
173- **No SLA** guarantees
174- **Limited regions** initially
175- **No autoscaling** - manual via `getRandom()`
176- **Rolling deploys** only (not instant like Workers)
177 
178Plan for API changes, test thoroughly before production.
179