Cloudflare

Gotchas & Limits

Common Errors

"Worker not found"

Cause: Attempting to get Worker that doesn't exist in namespace Solution: Catch error and return 404:

try {
  const userWorker = env.DISPATCHER.get(workerName);
  return userWorker.fetch(request);
} catch (e) {
  if (e.message.startsWith("Worker not found")) {
    return new Response("Worker not found", { status: 404 });
  }
  throw e;  // Re-throw unexpected errors
}

"CPU time limit exceeded"

Cause: User Worker exceeded configured CPU time limit Solution: Track violations in Analytics Engine and return 429 response; consider adjusting limits per customer tier

"Hostname Routing Issues"

Cause: DNS proxy settings causing routing problems Solution: Use */* wildcard route which works regardless of proxy settings for orange-to-orange routing

"Bindings Lost on Update"

Cause: Not using keep_bindings flag when updating Worker Solution: Use keep_bindings: true in API requests to preserve existing bindings during updates

"Tag Filtering Not Working"

Cause: Special characters not URL encoded in tag filters Solution: URL encode tags (e.g., tags=production%3Ayes) and avoid special chars like , and &

"Deploy Failures with ES Modules"

Cause: Incorrect upload format for ES modules Solution: Use multipart form upload, specify main_module in metadata, and set file type to application/javascript+module

"Static Asset Upload Failed"

Cause: Invalid hash format, expired token, or incorrect encoding Solution: Hash must be first 16 bytes (32 hex chars) of SHA-256, upload within 1 hour of session creation, deploy within 1 hour of upload completion, and Base64 encode file contents

"Outbound Worker Not Intercepting Calls"

Cause: Outbound Workers don't intercept Durable Object or mTLS binding fetch Solution: Plan egress control accordingly; not all fetch calls are intercepted

"TCP Socket Connection Failed"

Cause: Outbound Worker enabled blocks connect() API for TCP sockets Solution: Outbound Workers only intercept fetch() calls; TCP socket connections unavailable when outbound configured. Remove outbound if TCP needed, or use proxy pattern.

"API Rate Limit Exceeded"

Cause: Exceeded Cloudflare API rate limits (1200 requests per 5 minutes per account, 200 requests per second per IP) Solution: Implement exponential backoff:

async function deployWithBackoff(deploy: () => Promise<void>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await deploy();
    } catch (e) {
      if (e.status === 429 && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
        continue;
      }
      throw e;
    }
  }
}

"Gradual Deployment Not Supported"

Cause: Attempted to use gradual deployments with user Workers Solution: Gradual deployments not supported for Workers in dispatch namespaces. Use all-at-once deployment with staged rollout via dispatch worker logic (feature flags, percentage-based routing).

"Asset Session Expired"

Cause: Upload JWT expired (1 hour validity) or completion token expired (1 hour after upload) Solution: Complete asset upload within 1 hour of session creation, and deploy Worker within 1 hour of upload completion. For large uploads, batch files or increase upload parallelism.

Platform Limits

Asset Upload Limits

API Rate Limits

See Cloudflare API Rate Limits for details.

Operational Limits

See README.md, configuration.md, api.md, patterns.md