Workerd Gotchas

Common Errors

"Missing compatibility date"

Cause: Compatibility date not set Solution: ❌ Wrong:

const worker :Workerd.Worker = (
  serviceWorkerScript = embed "worker.js"
)

✅ Correct:

const worker :Workerd.Worker = (
  serviceWorkerScript = embed "worker.js",
  compatibilityDate = "2024-01-15"  # Always set!
)

Wrong Binding Type

Problem: JSON not parsed Cause: Using text = '{"key":"value"}' instead of json Solution: Use json = '{"key":"value"}' for parsed objects

Service vs Namespace

Problem: Cannot create DO instance Cause: Using service = "room-service" for Durable Object Solution: Use durableObjectNamespace = "Room" for DO bindings

Module Name Mismatch

Problem: Import fails Cause: Module name includes path: name = "src/index.js" Solution: Use simple names: name = "index.js", embed with path

Network Access

Problem: Fetch fails with network error Cause: No network service configured (workerd has no global fetch) Solution: Add network service binding:

services = [(name = "internet", network = (allow = ["public"]))]
bindings = [(name = "NET", service = "internet")]

Or external service:

bindings = [(name = "API", service = (external = (address = "api.com:443", http = (style = tls))))]

"Worker not responding"

Cause: Socket misconfigured, no fetch handler, or port unavailable Solution: Verify socket address matches, worker exports fetch(), port available

"Binding not found"

Cause: Name mismatch or service doesn't exist Solution: Check binding name in config matches code (env.BINDING for ES modules)

"Module not found"

Cause: Module name doesn't match import or bad embed path Solution: Module name must match import path exactly, verify embed path

"Compatibility error"

Cause: Date not set or API unavailable on that date Solution: Set compatibilityDate, verify API available on that date

Performance Issues

Problem: High memory usage Cause: Large caches or many isolates Solution: Set cache limits, reduce isolate count, or use V8 flags (caution)

Problem: Slow startup Cause: Many modules or complex config Solution: Compile to binary (workerd compile), reduce imports

Problem: Request timeouts Cause: External service issues or DNS problems Solution: Check connectivity, DNS resolution, TLS handshake

Build Issues

Problem: Cap'n Proto syntax errors Cause: Invalid config or missing schema Solution: Install capnproto tools, validate: capnp compile -I. config.capnp

Problem: Embed path not found Cause: Path relative to config file Solution: Use correct relative path or absolute path

Problem: V8 flags cause crashes Cause: Unsafe V8 flags Solution: ⚠️ V8 flags unsupported in production. Test thoroughly before use.

Security Issues

Problem: Hardcoded secrets in config Cause: text binding with secret value Solution: Use fromEnvironment to load from env vars

Problem: Overly broad network access Cause: network = (allow = ["*"]) Solution: Restrict to allow = ["public"] or specific hosts

Problem: Extractable crypto keys Cause: cryptoKey = (extractable = true, ...) Solution: Set extractable = false unless export required

Compatibility Changes

Problem: Breaking changes after compat date update Cause: New flags enabled between dates Solution: Review compat dates docs, test locally first

Problem: "Compatibility date not supported" Cause: Workerd version older than compat date Solution: Update workerd binary (version = max compat date supported)

Limits

Troubleshooting Steps

1. Enable verbose logging: workerd serve config.capnp --verbose
2. Check logs: Look for error messages, stack traces
3. Validate config: capnp compile -I. config.capnp
4. Test bindings: Log Object.keys(env) to verify
5. Check versions: Workerd version vs compat date
6. Isolate issue: Minimal repro config
7. Review schema: workerd.capnp

See configuration.md for config details, patterns.md for working examples, api.md for runtime APIs.