Cloudflare

Gotchas & Debugging

Common Errors

"Step Timeout"

Cause: Step execution exceeding 10 minute default timeout or configured timeout Solution: Set custom timeout with step.do('long operation', {timeout: '30 minutes'}, async () => {...}) or increase CPU limit in wrangler.jsonc (max 5min CPU time)

"waitForEvent Timeout"

Cause: Event not received within timeout period (default 24h, max 365d) Solution: Wrap in try-catch to handle timeout gracefully and proceed with default behavior

"Non-Deterministic Step Names"

Cause: Using dynamic values like Date.now() in step names causes replay issues Solution: Use deterministic values like event.instanceId for step names

"State Lost in Variables"

Cause: Using module-level or local variables to store state which is lost on hibernation Solution: Return values from step.do() which are automatically persisted: const total = await step.do('step 1', async () => 10)

"Non-Deterministic Conditionals"

Cause: Using non-deterministic logic (like Date.now()) outside steps in conditionals Solution: Move non-deterministic operations inside steps: const isLate = await step.do('check', async () => Date.now() > deadline)

"Large Step Returns Exceeding Limit"

Cause: Returning data >1 MiB from step Solution: Store large data in R2 and return only reference: { key: 'r2-object-key' }

"Step Exceeded CPU Limit But Ran for < 30s"

Cause: Confusion between CPU time (active compute) and wall-clock time (includes I/O waits) Solution: Network requests, database queries, and sleeps don't count toward CPU. 30s limit = 30s of active processing

"Idempotency Violation"

Cause: Step operations not idempotent, causing duplicate charges or actions on retry Solution: Check if operation already completed before executing (e.g., check if customer already charged)

"Instance ID Collision"

Cause: Reusing instance IDs causing conflicts Solution: Use unique IDs with timestamp: await env.MY_WORKFLOW.create({ id: \${userId}-${Date.now()}`, params: {} })`

"Instance Data Disappeared After Completion"

Cause: Completed/errored instances are automatically deleted after retention period (3 days free / 30 days paid) Solution: Export critical data to KV/R2/D1 before workflow completes

"Missing await on step.do"

Cause: Forgetting to await step.do() causing fire-and-forget behavior Solution: Always await step operations: await step.do('task', ...)

Limits

Note: Instances in waiting state (from step.sleep or step.waitForEvent) don't count toward concurrent instance limit, allowing millions of sleeping workflows.

Pricing

References

• Official Docs

• Get Started Guide

• Workers API

• REST API

• Examples

• Limits

• Pricing

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