1# Smart Placement Gotchas
2 
3## Common Errors
4 
5### "INSUFFICIENT_INVOCATIONS"
6 
7**Cause:** Not enough traffic for Smart Placement to analyze
8**Solution:**
9- Ensure Worker receives consistent global traffic
10- Wait longer (analysis takes up to 15 minutes)
11- Send test traffic from multiple global locations
12- Check Worker has fetch event handler
13 
14### "UNSUPPORTED_APPLICATION"
15 
16**Cause:** Smart Placement made Worker slower rather than faster
17**Reasons:**
18- Worker doesn't make backend calls (runs faster at edge)
19- Backend calls are cached (network latency to user more important)
20- Backend service has good global distribution
21- Worker serves static assets or Pages content
22 
23**Solutions:**
24- Disable Smart Placement: `{ "placement": { "mode": "off" } }`
25- Review whether Worker actually benefits from Smart Placement
26- Consider caching strategy to reduce backend calls
27- For Pages/Assets Workers, use separate backend Worker with Smart Placement
28 
29### "No request duration metrics"
30 
31**Cause:** Smart Placement not enabled, insufficient time passed, insufficient traffic, or analysis incomplete
32**Solution:**
33- Ensure Smart Placement enabled in config
34- Wait 15+ minutes after deployment
35- Verify Worker has sufficient traffic
36- Check `placement_status` is `SUCCESS`
37 
38### "cf-placement header missing"
39 
40**Cause:** Smart Placement not enabled, beta feature removed, or Worker not analyzed yet
41**Solution:** Verify Smart Placement enabled, wait for analysis (15min), check if beta feature still available
42 
43## Pages/Assets + Smart Placement Performance Degradation
44 
45**Problem:** Static assets load 2-5x slower when Smart Placement enabled with `run_worker_first = true`.
46 
47**Cause:** Smart Placement routes ALL requests (including static assets like HTML, CSS, JS, images) to remote locations. Static content should ALWAYS be served from edge closest to user.
48 
49**Solution:** Split into separate Workers OR disable Smart Placement:
50```jsonc
51// ❌ BAD - Assets routed away from user
52{
53  "name": "pages-app",
54  "placement": { "mode": "smart" },
55  "assets": { "run_worker_first": true }
56}
57 
58// ✅ GOOD - Assets at edge, API optimized
59// frontend/wrangler.jsonc
60{
61  "name": "frontend",
62  "assets": { "run_worker_first": true }
63  // No placement field - stays at edge
64}
65 
66// backend/wrangler.jsonc
67{
68  "name": "backend-api",
69  "placement": { "mode": "smart" }
70}
71```
72 
73This is one of the most common and impactful Smart Placement misconfigurations.
74 
75## Monolithic Full-Stack Worker
76 
77**Problem:** Frontend and backend logic in single Worker with Smart Placement enabled.
78 
79**Cause:** Smart Placement optimizes for backend latency but increases user-facing response time.
80 
81**Solution:** Split into two Workers:
82```jsonc
83// frontend/wrangler.jsonc
84{
85  "name": "frontend",
86  "placement": { "mode": "off" },  // Explicit: stay at edge
87  "services": [{ "binding": "BACKEND", "service": "backend-api" }]
88}
89 
90// backend/wrangler.jsonc
91{
92  "name": "backend-api",
93  "placement": { "mode": "smart" },
94  "d1_databases": [{ "binding": "DB", "database_id": "xxx" }]
95}
96```
97 
98## Local Development Confusion
99 
100**Issue:** Smart Placement doesn't work in `wrangler dev`.
101 
102**Explanation:** Smart Placement only activates in production deployments, not local development.
103 
104**Solution:** Test Smart Placement in staging environment: `wrangler deploy --env staging`
105 
106## Baseline Traffic & Analysis Time
107 
108**Note:** Smart Placement routes 1% of requests WITHOUT optimization for comparison (expected).
109 
110**Analysis time:** Up to 15 minutes. During analysis, Worker runs at edge. Monitor `placement_status`.
111 
112## RPC Methods Not Affected (Critical Limitation)
113 
114**Problem:** Enabled Smart Placement on backend but RPC calls still slow.
115 
116**Cause:** Smart Placement ONLY affects `fetch` handlers. RPC methods (Service Bindings with `WorkerEntrypoint`) are NEVER affected.
117 
118**Why:** RPC bypasses `fetch` handler - Smart Placement can only route `fetch` requests.
119 
120**Solution:** Convert to fetch-based Service Bindings:
121 
122```typescript
123// ❌ RPC - Smart Placement has NO EFFECT
124export class BackendRPC extends WorkerEntrypoint {
125  async getData() {
126    // ALWAYS runs at edge
127    return await this.env.DATABASE.prepare('SELECT * FROM table').all();
128  }
129}
130 
131// ✅ Fetch - Smart Placement WORKS
132export default {
133  async fetch(request: Request, env: Env): Promise<Response> {
134    // Runs close to DATABASE when Smart Placement enabled
135    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
136    return Response.json(data);
137  }
138}
139```
140 
141## Requirements
142 
143- **Wrangler 2.20.0+** required
144- **Consistent multi-region traffic** needed for analysis
145- **Only affects fetch handlers** - RPC methods and named entrypoints not affected
146 
147## Limits
148 
149| Resource/Limit | Value | Notes |
150|----------------|-------|-------|
151| Analysis time | Up to 15 minutes | After enabling |
152| Baseline traffic | 1% | Routed without optimization |
153| Min Wrangler version | 2.20.0+ | Required |
154| Traffic requirement | Multi-region | Consistent needed |
155 
156## Disabling Smart Placement
157 
158```jsonc
159{ "placement": { "mode": "off" } }  // Explicit disable
160// OR remove "placement" field entirely (same effect)
161```
162 
163Both behaviors identical - Worker runs at edge closest to user.
164 
165## When NOT to Use Smart Placement
166 
167- Workers serving only static content or cached responses
168- Workers without significant backend communication
169- Pure edge logic (auth checks, redirects, simple transformations)
170- Workers without fetch event handlers
171- Pages/Assets Workers with `run_worker_first = true`
172- Workers using RPC methods instead of fetch handlers
173 
174These scenarios won't benefit and may perform worse with Smart Placement.
175