1# Workerd Gotchas
2 
3## Common Errors
4 
5### "Missing compatibility date"
6**Cause:** Compatibility date not set
7**Solution:**
8❌ Wrong:
9```capnp
10const worker :Workerd.Worker = (
11  serviceWorkerScript = embed "worker.js"
12)
13```
14 
15✅ Correct:
16```capnp
17const worker :Workerd.Worker = (
18  serviceWorkerScript = embed "worker.js",
19  compatibilityDate = "2024-01-15"  # Always set!
20)
21```
22 
23### Wrong Binding Type
24**Problem:** JSON not parsed
25**Cause:** Using `text = '{"key":"value"}'` instead of `json`
26**Solution:** Use `json = '{"key":"value"}'` for parsed objects
27 
28### Service vs Namespace
29**Problem:** Cannot create DO instance
30**Cause:** Using `service = "room-service"` for Durable Object
31**Solution:** Use `durableObjectNamespace = "Room"` for DO bindings
32 
33### Module Name Mismatch
34**Problem:** Import fails
35**Cause:** Module name includes path: `name = "src/index.js"`
36**Solution:** Use simple names: `name = "index.js"`, embed with path
37 
38## Network Access
39 
40**Problem:** Fetch fails with network error
41**Cause:** No network service configured (workerd has no global fetch)
42**Solution:** Add network service binding:
43```capnp
44services = [(name = "internet", network = (allow = ["public"]))]
45bindings = [(name = "NET", service = "internet")]
46```
47 
48Or external service:
49```capnp
50bindings = [(name = "API", service = (external = (address = "api.com:443", http = (style = tls))))]
51```
52 
53### "Worker not responding"
54**Cause:** Socket misconfigured, no fetch handler, or port unavailable
55**Solution:** Verify socket `address` matches, worker exports `fetch()`, port available
56 
57### "Binding not found"
58**Cause:** Name mismatch or service doesn't exist
59**Solution:** Check binding name in config matches code (`env.BINDING` for ES modules)
60 
61### "Module not found"
62**Cause:** Module name doesn't match import or bad embed path
63**Solution:** Module `name` must match import path exactly, verify `embed` path
64 
65### "Compatibility error"
66**Cause:** Date not set or API unavailable on that date
67**Solution:** Set `compatibilityDate`, verify API available on that date
68 
69## Performance Issues
70 
71**Problem:** High memory usage
72**Cause:** Large caches or many isolates
73**Solution:** Set cache limits, reduce isolate count, or use V8 flags (caution)
74 
75**Problem:** Slow startup
76**Cause:** Many modules or complex config
77**Solution:** Compile to binary (`workerd compile`), reduce imports
78 
79**Problem:** Request timeouts
80**Cause:** External service issues or DNS problems
81**Solution:** Check connectivity, DNS resolution, TLS handshake
82 
83## Build Issues
84 
85**Problem:** Cap'n Proto syntax errors
86**Cause:** Invalid config or missing schema
87**Solution:** Install capnproto tools, validate: `capnp compile -I. config.capnp`
88 
89**Problem:** Embed path not found
90**Cause:** Path relative to config file
91**Solution:** Use correct relative path or absolute path
92 
93**Problem:** V8 flags cause crashes
94**Cause:** Unsafe V8 flags
95**Solution:** ⚠️ V8 flags unsupported in production. Test thoroughly before use.
96 
97## Security Issues
98 
99**Problem:** Hardcoded secrets in config
100**Cause:** `text` binding with secret value
101**Solution:** Use `fromEnvironment` to load from env vars
102 
103**Problem:** Overly broad network access
104**Cause:** `network = (allow = ["*"])`
105**Solution:** Restrict to `allow = ["public"]` or specific hosts
106 
107**Problem:** Extractable crypto keys
108**Cause:** `cryptoKey = (extractable = true, ...)`
109**Solution:** Set `extractable = false` unless export required
110 
111## Compatibility Changes
112 
113**Problem:** Breaking changes after compat date update
114**Cause:** New flags enabled between dates
115**Solution:** Review [compat dates docs](https://developers.cloudflare.com/workers/configuration/compatibility-dates/), test locally first
116 
117**Problem:** "Compatibility date not supported"
118**Cause:** Workerd version older than compat date
119**Solution:** Update workerd binary (version = max compat date supported)
120 
121## Limits
122 
123| Resource/Limit | Value | Notes |
124|----------------|-------|-------|
125| V8 flags | Unsupported in production | Use with caution |
126| Compatibility date | Must match workerd version | Update if mismatch |
127| Module count | Affects startup time | Many imports slow |
128 
129## Troubleshooting Steps
130 
1311. **Enable verbose logging**: `workerd serve config.capnp --verbose`
1322. **Check logs**: Look for error messages, stack traces
1333. **Validate config**: `capnp compile -I. config.capnp`
1344. **Test bindings**: Log `Object.keys(env)` to verify
1355. **Check versions**: Workerd version vs compat date
1366. **Isolate issue**: Minimal repro config
1377. **Review schema**: [workerd.capnp](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/workerd.capnp)
138 
139See [configuration.md](./configuration.md) for config details, [patterns.md](./patterns.md) for working examples, [api.md](./api.md) for runtime APIs.
140