1# Wrangler Common Issues
2 
3## Common Errors
4 
5### "Binding ID vs name mismatch"
6 
7**Cause:** Confusion between binding name (code) and resource ID
8**Solution:** Bindings use `binding` (code name) and `id`/`database_id`/`bucket_name` (resource ID). Preview bindings need separate IDs: `preview_id`, `preview_database_id`
9 
10### "Environment not inheriting config"
11 
12**Cause:** Non-inheritable keys not redefined per environment
13**Solution:** Non-inheritable keys (bindings, vars) must be redefined per environment. Inheritable keys (routes, compatibility_date) can be overridden
14 
15### "Local dev behavior differs from production"
16 
17**Cause:** Using local simulation instead of remote execution
18**Solution:** Choose appropriate remote mode:
19- `wrangler dev` (default): Local simulation, fast, limited accuracy
20- `wrangler dev --remote`: Full remote execution, production-accurate, slower
21- Use `remote: "minimal"` in tests for fast tests with real remote bindings
22 
23### "startWorker doesn't match production"
24 
25**Cause:** Using local mode when remote resources needed
26**Solution:** Use `remote` option:
27```typescript
28const worker = await startWorker({ 
29  config: "wrangler.jsonc",
30  remote: true  // or "minimal" for faster tests
31});
32```
33 
34### "Unexpected runtime changes"
35 
36**Cause:** Missing compatibility_date
37**Solution:** Always set `compatibility_date`:
38```jsonc
39{ "compatibility_date": "2025-01-01" }
40```
41 
42### "Durable Object binding not working"
43 
44**Cause:** Missing script_name for external DOs
45**Solution:** Always specify `script_name` for external Durable Objects:
46```jsonc
47{
48  "durable_objects": {
49    "bindings": [
50      { "name": "MY_DO", "class_name": "MyDO", "script_name": "my-worker" }
51    ]
52  }
53}
54```
55 
56For local DOs in same Worker, `script_name` is optional.
57 
58### "Auto-provisioned resources not appearing"
59 
60**Cause:** IDs written back to config on first deploy, but config not reloaded
61**Solution:** After first deploy with auto-provisioning, config file is updated with IDs. Commit the updated config. On subsequent deploys, existing resources are reused.
62 
63### "Secrets not available in local dev"
64 
65**Cause:** Secrets set with `wrangler secret put` only work in deployed Workers
66**Solution:** For local dev, use `.dev.vars`
67 
68### "Node.js compatibility error"
69 
70**Cause:** Missing Node.js compatibility flag
71**Solution:** Some bindings (Hyperdrive with `pg`) require:
72```jsonc
73{ "compatibility_flags": ["nodejs_compat"] }
74```
75 
76### "Workers Assets 404 errors"
77 
78**Cause:** Asset path mismatch or incorrect `html_handling`
79**Solution:** 
80- Check `assets.directory` points to correct build output
81- Set `html_handling: "auto-trailing-slash"` for SPAs
82- Use `not_found_handling: "single-page-application"` to serve index.html for 404s
83```jsonc
84{
85  "assets": {
86    "directory": "./dist",
87    "html_handling": "auto-trailing-slash",
88    "not_found_handling": "single-page-application"
89  }
90}
91```
92 
93### "Placement not reducing latency"
94 
95**Cause:** Misunderstanding of Smart Placement
96**Solution:** Smart Placement only helps when Worker accesses D1 or Durable Objects. It doesn't affect KV, R2, or external API latency.
97```jsonc
98{ "placement": { "mode": "smart" } }  // Only beneficial with D1/DOs
99```
100 
101### "unstable_startWorker not found"
102 
103**Cause:** Using outdated API
104**Solution:** Use stable `startWorker` instead:
105```typescript
106import { startWorker } from "wrangler";  // Not unstable_startWorker
107```
108 
109### "outboundService not mocking fetch"
110 
111**Cause:** Mock function not returning Response
112**Solution:** Always return Response, use `fetch(req)` for passthrough:
113```typescript
114const worker = await startWorker({
115  outboundService: (req) => {
116    if (shouldMock(req)) {
117      return new Response("mocked");
118    }
119    return fetch(req);  // Required for non-mocked requests
120  }
121});
122```
123 
124## Limits
125 
126| Resource/Limit | Value | Notes |
127|----------------|-------|-------|
128| Bindings per Worker | 64 | Total across all types |
129| Environments | Unlimited | Named envs in config |
130| Config file size | ~1MB | Keep reasonable |
131| Workers Assets size | 25 MB | Per deployment |
132| Workers Assets files | 20,000 | Max number of files |
133| Script size (compressed) | 1 MB | Free, 10 MB paid |
134| CPU time | 10ms | Free, 30s default (5min max) paid |
135| Subrequest limit | 50 | Free, 10,000 paid |
136 
137## Troubleshooting
138 
139### Authentication Issues
140```bash
141wrangler logout
142wrangler login
143wrangler whoami
144```
145 
146### Configuration Errors
147```bash
148wrangler check startup  # Profile Worker startup time and detect scripts exceeding the startup time limit
149```
150Use wrangler.jsonc with `$schema` for validation.
151 
152### Binding Not Available
153- Check binding exists in config
154- For environments, ensure binding defined for that env
155- Local dev: some bindings need `--remote`
156 
157### Deployment Failures
158```bash
159wrangler tail              # Check logs
160wrangler deploy --dry-run  # Validate
161wrangler whoami            # Check account limits
162```
163 
164### Local Development Issues
165```bash
166rm -rf .wrangler/state     # Clear local state
167wrangler dev --remote      # Use remote bindings
168wrangler dev --persist-to ./local-state  # Custom persist location
169wrangler dev --inspector-port 9229  # Enable debugging
170```
171 
172### Testing Issues
173```bash
174# If tests hang, ensure dispose() is called
175worker.dispose()  // Always cleanup
176 
177# If bindings don't work in tests
178const worker = await startWorker({ 
179  config: "wrangler.jsonc",
180  remote: "minimal"  // Use remote bindings
181});
182```
183 
184## Resources
185 
186- Docs: https://developers.cloudflare.com/workers/wrangler/
187- Config: https://developers.cloudflare.com/workers/wrangler/configuration/
188- Commands: https://developers.cloudflare.com/workers/wrangler/commands/
189- Examples: https://github.com/cloudflare/workers-sdk/tree/main/templates
190- Discord: https://discord.gg/cloudflaredev
191 
192## See Also
193 
194- [README.md](./README.md) - Commands
195- [configuration.md](./configuration.md) - Config
196- [api.md](./api.md) - Programmatic API
197- [patterns.md](./patterns.md) - Workflows
198