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/containers/gotchas.md

Critical Gotchas

⚠️ WebSocket: fetch() vs containerFetch()

Problem: WebSocket connections fail silently

Cause: containerFetch() doesn't support WebSocket upgrades

Fix: Always use fetch() for WebSocket

// ❌ WRONG
return container.containerFetch(request);

// ✅ CORRECT
return container.fetch(request);

⚠️ startAndWaitForPorts() vs start()

Problem: "connection refused" after start()

Cause: start() returns when process starts, NOT when ports ready

Fix: Use startAndWaitForPorts() before requests

// ❌ WRONG
await container.start();
return container.fetch(request);

// ✅ CORRECT
await container.startAndWaitForPorts();
return container.fetch(request);

⚠️ Activity Timeout on Long Operations

Problem: Container stops during long work

Cause: sleepAfter based on request activity, not internal work

Fix: Renew timeout by touching storage

const interval = setInterval(() => {
  this.ctx.storage.put("keepalive", Date.now());
}, 60000);

try {
  await this.doLongWork(data);
} finally {
  clearInterval(interval);
}

⚠️ blockConcurrencyWhile for Startup

Problem: Race conditions during initialization

Fix: Use blockConcurrencyWhile for atomic initialization

await this.ctx.blockConcurrencyWhile(async () => {
  if (!this.initialized) {
    await this.startAndWaitForPorts();
    this.initialized = true;
  }
});

⚠️ Lifecycle Hooks Block Requests

Problem: Container unresponsive during onStart()

Cause: Hooks run in blockConcurrencyWhile - no concurrent requests

Fix: Keep hooks fast, avoid long operations

⚠️ Don't Override alarm() When Using schedule()

Problem: Scheduled tasks don't execute

Cause: schedule() uses alarm() internally

Fix: Implement alarm() to handle scheduled tasks

Common Errors

"Container start timeout"

Cause: Container took >8s (start()) or >20s (startAndWaitForPorts())

Solutions:

  • Optimize image (smaller base, fewer layers)
  • Check entrypoint correct
  • Verify app listens on correct ports
  • Increase timeout if needed

"Port not available"

Cause: Calling fetch() before port ready

Solution: Use startAndWaitForPorts()

"Container memory exceeded"

Cause: Using more memory than instance type allows

Solutions:

  • Use larger instance type (standard-2, standard-3, standard-4)
  • Optimize app memory usage
  • Use custom instance type
"instance_type_custom": {
  "vcpu": 2,
  "memory_mib": 8192
}

"Max instances reached"

Cause: All max_instances slots in use

Solutions:

  • Increase max_instances
  • Implement proper sleepAfter
  • Use getRandom() for distribution
  • Check for instance leaks

"No container instance available"

Cause: Account capacity limits reached

Solutions:

  • Check account limits
  • Review instance types across containers
  • Contact Cloudflare support

Limits

| Resource | Limit | Notes | |----------|-------|-------| | Cold start | 2-3s | Image pre-fetched globally | | Graceful shutdown | 15 min | SIGTERM → SIGKILL | | start() timeout | 8s | Process start | | startAndWaitForPorts() timeout | 20s | Port ready | | Max vCPU per container | 4 | standard-4 or custom | | Max memory per container | 12 GiB | standard-4 or custom | | Max disk per container | 20 GB | Ephemeral, resets | | Account total memory | 400 GiB | All containers | | Account total vCPU | 100 | All containers | | Account total disk | 2 TB | All containers | | Image storage | 50 GB | Per account | | Disk persistence | None | Use DO storage |

Best Practices

  1. Use startAndWaitForPorts() by default - Prevents port errors
  2. Set appropriate sleepAfter - Balance resources vs cold starts
  3. Use fetch() for WebSocket - Not containerFetch()
  4. Design for restarts - Ephemeral disk, implement graceful shutdown
  5. Monitor resources - Stay within account limits
  6. Keep hooks fast - Run in blockConcurrencyWhile
  7. Renew activity for long ops - Touch storage to prevent timeout

Beta Caveats

⚠️ Containers in beta:

  • API may change without notice
  • No SLA guarantees
  • Limited regions initially
  • No autoscaling - manual via getRandom()
  • Rolling deploys only (not instant like Workers)

Plan for API changes, test thoroughly before production.