1# Gotchas & Limits
2 
3## Common Errors
4 
5### "Worker not found"
6 
7**Cause:** Attempting to get Worker that doesn't exist in namespace  
8**Solution:** Catch error and return 404:
9 
10```typescript
11try {
12  const userWorker = env.DISPATCHER.get(workerName);
13  return userWorker.fetch(request);
14} catch (e) {
15  if (e.message.startsWith("Worker not found")) {
16    return new Response("Worker not found", { status: 404 });
17  }
18  throw e;  // Re-throw unexpected errors
19}
20```
21 
22### "CPU time limit exceeded"
23 
24**Cause:** User Worker exceeded configured CPU time limit  
25**Solution:** Track violations in Analytics Engine and return 429 response; consider adjusting limits per customer tier
26 
27### "Hostname Routing Issues"
28 
29**Cause:** DNS proxy settings causing routing problems  
30**Solution:** Use `*/*` wildcard route which works regardless of proxy settings for orange-to-orange routing
31 
32### "Bindings Lost on Update"
33 
34**Cause:** Not using `keep_bindings` flag when updating Worker  
35**Solution:** Use `keep_bindings: true` in API requests to preserve existing bindings during updates
36 
37### "Tag Filtering Not Working"
38 
39**Cause:** Special characters not URL encoded in tag filters  
40**Solution:** URL encode tags (e.g., `tags=production%3Ayes`) and avoid special chars like `,` and `&`
41 
42### "Deploy Failures with ES Modules"
43 
44**Cause:** Incorrect upload format for ES modules  
45**Solution:** Use multipart form upload, specify `main_module` in metadata, and set file type to `application/javascript+module`
46 
47### "Static Asset Upload Failed"
48 
49**Cause:** Invalid hash format, expired token, or incorrect encoding  
50**Solution:** Hash must be first 16 bytes (32 hex chars) of SHA-256, upload within 1 hour of session creation, deploy within 1 hour of upload completion, and Base64 encode file contents
51 
52### "Outbound Worker Not Intercepting Calls"
53 
54**Cause:** Outbound Workers don't intercept Durable Object or mTLS binding fetch  
55**Solution:** Plan egress control accordingly; not all fetch calls are intercepted
56 
57### "TCP Socket Connection Failed"
58 
59**Cause:** Outbound Worker enabled blocks `connect()` API for TCP sockets  
60**Solution:** Outbound Workers only intercept `fetch()` calls; TCP socket connections unavailable when outbound configured. Remove outbound if TCP needed, or use proxy pattern.
61 
62### "API Rate Limit Exceeded"
63 
64**Cause:** Exceeded Cloudflare API rate limits (1200 requests per 5 minutes per account, 200 requests per second per IP)  
65**Solution:** Implement exponential backoff:
66 
67```typescript
68async function deployWithBackoff(deploy: () => Promise<void>, maxRetries = 3) {
69  for (let i = 0; i < maxRetries; i++) {
70    try {
71      return await deploy();
72    } catch (e) {
73      if (e.status === 429 && i < maxRetries - 1) {
74        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
75        continue;
76      }
77      throw e;
78    }
79  }
80}
81```
82 
83### "Gradual Deployment Not Supported"
84 
85**Cause:** Attempted to use gradual deployments with user Workers  
86**Solution:** Gradual deployments not supported for Workers in dispatch namespaces. Use all-at-once deployment with staged rollout via dispatch worker logic (feature flags, percentage-based routing).
87 
88### "Asset Session Expired"
89 
90**Cause:** Upload JWT expired (1 hour validity) or completion token expired (1 hour after upload)  
91**Solution:** Complete asset upload within 1 hour of session creation, and deploy Worker within 1 hour of upload completion. For large uploads, batch files or increase upload parallelism.
92 
93## Platform Limits
94 
95| Limit | Value | Notes |
96|-------|-------|-------|
97| Workers per namespace | Unlimited | Unlike regular Workers (500 per account) |
98| Namespaces per account | Unlimited | Best practice: 1 production + 1 staging |
99| Max tags per Worker | 8 | For filtering and organization |
100| Worker mode | Untrusted (default) | No `request.cf` access unless trusted mode |
101| Cache isolation | Per-Worker (untrusted) | Shared in trusted mode with key prefixes |
102| Durable Object namespaces | Unlimited | No per-account limit for WfP |
103| Gradual Deployments | Not supported | All-at-once only |
104| `caches.default` | Disabled (untrusted) | Use Cache API with custom keys |
105 
106## Asset Upload Limits
107 
108| Limit | Value | Notes |
109|-------|-------|-------|
110| Upload session JWT validity | 1 hour | Must complete upload within this time |
111| Completion token validity | 1 hour | Must deploy within this time after upload |
112| Asset hash format | First 16 bytes SHA-256 | 32 hex characters |
113| Base64 encoding | Required | For binary files |
114 
115## API Rate Limits
116 
117| Limit Type | Value | Scope |
118|------------|-------|-------|
119| Client API | 1200 requests / 5 min | Per account |
120| Client API | 200 requests / sec | Per IP address |
121| GraphQL | Varies by query cost | Query complexity |
122 
123See [Cloudflare API Rate Limits](https://developers.cloudflare.com/fundamentals/api/reference/limits/) for details.
124 
125## Operational Limits
126 
127| Operation | Limit | Notes |
128|-----------|-------|-------|
129| CPU time (custom limits) | Up to Workers plan limit | Set per-invocation in dispatch worker |
130| Subrequests (custom limits) | Up to Workers plan limit | Set per-invocation in dispatch worker |
131| Outbound Worker subrequests | Not intercepted for DO/mTLS | Only regular fetch() calls |
132| TCP sockets with outbound | Disabled | `connect()` API unavailable |
133 
134See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)
135