1# Gotchas & Best Practices
2 
3## Common Errors
4 
5### "Container running indefinitely"
6 
7**Cause:** `keepAlive: true` without calling `destroy()`
8**Solution:** Always call `destroy()` when done with keepAlive containers
9 
10```typescript
11const sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true });
12try {
13  const result = await sandbox.exec('python script.py');
14  return result.stdout;
15} finally {
16  await sandbox.destroy();  // REQUIRED to free resources
17}
18```
19 
20### "CONTAINER_NOT_READY"
21 
22**Cause:** Container still provisioning (first request or after sleep)
23**Solution:** Retry after 2-3s
24 
25```typescript
26async function execWithRetry(sandbox, cmd) {
27  for (let i = 0; i < 3; i++) {
28    try {
29      return await sandbox.exec(cmd);
30    } catch (e) {
31      if (e.code === 'CONTAINER_NOT_READY') {
32        await new Promise(r => setTimeout(r, 2000));
33        continue;
34      }
35      throw e;
36    }
37  }
38}
39```
40 
41### "Connection refused: container port not found"
42 
43**Cause:** Missing `EXPOSE` directive in Dockerfile
44**Solution:** Add `EXPOSE <port>` to Dockerfile (only needed for `wrangler dev`, production auto-exposes)
45 
46### "Preview URLs not working"
47 
48**Cause:** Custom domain not configured, wildcard DNS missing, `normalizeId` not set, or `proxyToSandbox()` not called
49**Solution:** Check:
501. Custom domain configured? (not `.workers.dev`)
512. Wildcard DNS set up? (`*.domain.com → worker.domain.com`)
523. `normalizeId: true` in getSandbox?
534. `proxyToSandbox()` called first in fetch?
54 
55### "Slow first request"
56 
57**Cause:** Cold start (container provisioning)
58**Solution:**
59- Use `sleepAfter` instead of creating new sandboxes
60- Pre-warm with cron triggers
61- Set `keepAlive: true` for critical sandboxes
62 
63### "File not persisting"
64 
65**Cause:** Files in `/tmp` or other ephemeral paths
66**Solution:** Use `/workspace` for persistent files
67 
68### "Bucket mounting doesn't work locally"
69 
70**Cause:** Bucket mounting requires FUSE, not available in `wrangler dev`
71**Solution:** Test bucket mounting in production only. Use mock data locally.
72 
73### "Different normalizeId = different sandbox"
74 
75**Cause:** Changing `normalizeId` option changes Durable Object ID
76**Solution:** Set `normalizeId` consistently. `normalizeId: true` lowercases the ID.
77 
78```typescript
79// These create DIFFERENT sandboxes:
80getSandbox(env.Sandbox, 'MyApp');              // DO ID: hash('MyApp')
81getSandbox(env.Sandbox, 'MyApp', { normalizeId: true });  // DO ID: hash('myapp')
82```
83 
84### "Code context variables disappeared"
85 
86**Cause:** Container restart clears code context state
87**Solution:** Code contexts are ephemeral. Recreate context after container sleep/wake.
88 
89## Performance Optimization
90 
91### Sandbox ID Strategy
92 
93```typescript
94// ❌ BAD: New sandbox every time (slow)
95const sandbox = getSandbox(env.Sandbox, `user-${Date.now()}`);
96 
97// ✅ GOOD: Reuse per user
98const sandbox = getSandbox(env.Sandbox, `user-${userId}`);
99```
100 
101### Sleep & Traffic Config
102 
103```typescript
104// Cost-optimized
105getSandbox(env.Sandbox, 'id', { sleepAfter: '30m', keepAlive: false });
106 
107// Always-on (requires destroy())
108getSandbox(env.Sandbox, 'id', { keepAlive: true });
109```
110 
111```jsonc
112// High traffic: increase max_instances
113{ "containers": [{ "class_name": "Sandbox", "max_instances": 50 }] }
114```
115 
116## Security Best Practices
117 
118### Sandbox Isolation
119- Each sandbox = isolated container (filesystem, network, processes)
120- Use unique sandbox IDs per tenant for multi-tenant apps
121- Sandboxes cannot communicate directly
122 
123### Input Validation
124 
125```typescript
126// ❌ DANGEROUS: Command injection
127const result = await sandbox.exec(`python3 -c "${userCode}"`);
128 
129// ✅ SAFE: Write to file, execute file
130await sandbox.writeFile('/workspace/user_code.py', userCode);
131const result = await sandbox.exec('python3 /workspace/user_code.py');
132```
133 
134### Resource Limits
135 
136```typescript
137// Timeout long-running commands
138const result = await sandbox.exec('python3 script.py', {
139  timeout: 30000  // 30 seconds
140});
141```
142 
143### Secrets Management
144 
145```typescript
146// ❌ NEVER hardcode secrets
147const token = 'ghp_abc123';
148 
149// ✅ Use environment secrets
150const token = env.GITHUB_TOKEN;
151 
152// Pass to sandbox via exec env
153const result = await sandbox.exec('git clone ...', {
154  env: { GIT_TOKEN: token }
155});
156```
157 
158### Preview URL Security
159Preview URLs include auto-generated tokens:
160```
161https://8080-sandbox-abc123def456.yourdomain.com
162```
163Token changes on each expose operation, preventing unauthorized access.
164 
165## Limits
166 
167| Resource | Lite | Standard | Heavy |
168|----------|------|----------|-------|
169| RAM | 256MB | 512MB | 1GB |
170| vCPU | 0.5 | 1 | 2 |
171 
172| Operation | Default Timeout | Override |
173|-----------|----------------|----------|
174| Container provisioning | 30s | `SANDBOX_INSTANCE_TIMEOUT_MS` |
175| Port readiness | 90s | `SANDBOX_PORT_TIMEOUT_MS` |
176| exec() | None (no default) | `timeout` option |
177| sleepAfter | 10m | `sleepAfter` option |
178 
179**Performance**:
180- **First deploy**: 2-3 min for container build
181- **Cold start**: 2-3s when waking from sleep
182- **Bucket mounting**: Production only (FUSE not in dev)
183 
184## Production Guide
185 
186See: https://developers.cloudflare.com/sandbox/guides/production-deployment/
187 
188## Resources
189 
190- [Official Docs](https://developers.cloudflare.com/sandbox/)
191- [API Reference](https://developers.cloudflare.com/sandbox/api/)
192- [Examples](https://github.com/cloudflare/sandbox-sdk/tree/main/examples)
193- [npm Package](https://www.npmjs.com/package/@cloudflare/sandbox)
194- [Discord Support](https://discord.cloudflare.com)
195