AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/workerd/gotchas.md

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

| Resource/Limit | Value | Notes | |----------------|-------|-------| | V8 flags | Unsupported in production | Use with caution | | Compatibility date | Must match workerd version | Update if mismatch | | Module count | Affects startup time | Many imports slow |

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.