dotfiles/.agents/skills/cloudflare-deploy/references/snippets/gotchas.md

Gotchas & Best Practices

Common Errors

1000: "Snippet execution failed"

Runtime error or syntax error. Wrap code in try/catch:

try { return await fetch(request); }
catch (error) { return new Response(`Error: ${error.message}`, { status: 500 }); }

1100: "Exceeded execution limit"

Code takes >5ms CPU. Simplify logic or move to Workers.

1201: "Multiple origin fetches"

Call fetch(request) exactly once:

// ❌ Multiple origin fetches
const r1 = await fetch(request); const r2 = await fetch(request);
// ✅ Single fetch, reuse response
const response = await fetch(request);

1202: "Subrequest limit exceeded"

Pro: 2 subrequests, Business/Enterprise: 5. Reduce fetch calls.

"Cannot set property on immutable object"

Clone before modifying:

const modifiedRequest = new Request(request);
modifiedRequest.headers.set("X-Custom", "value");

"caches is not defined"

Cache API NOT available in Snippets. Use Workers.

"Module not found"

Snippets don't support import. Use inline code or Workers.

Best Practices

Performance

• Keep code <10KB (32KB limit)
• Optimize for 5ms CPU
• Clone only when modifying
• Minimize subrequests

Security

• Validate all inputs
• Use Web Crypto API for hashing
• Sanitize headers before origin
• Don't log secrets

Debugging

newResponse.headers.set("X-Debug-Country", request.cf.country);

curl -H "X-Test: true" https://example.com -v

Available APIs

✅ Available: fetch(), Request, Response, Headers, URL, crypto.subtle, crypto.randomUUID(), atob()/btoa(), JSON

❌ NOT Available: caches, KV, D1, R2, Durable Objects, WebSocket, HTMLRewriter, import, Node.js APIs

Limits

Resource	Limit
Snippet size	32KB
Execution time	5ms CPU
Subrequests (Pro/Biz)	2/5
Snippets/zone	20

Performance Benchmarks

Operation	Time
Header set	<0.1ms
URL parsing	<0.2ms
fetch()	1-3ms
SHA-256	0.5-1ms

Migrate to Workers when: >5ms needed, >5 subrequests, need storage (KV/D1/R2), need npm packages, >32KB code