Cloudflare

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

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.