1# Gotchas & Debugging
2 
3## Common Errors
4 
5### "Step Timeout"
6 
7**Cause:** Step execution exceeding the default or configured timeout  
8**Solution:** Set custom timeout with `step.do('long operation', {timeout: '30 minutes'}, async () => {...})` or increase CPU limit via `limits.cpu_ms` in wrangler.jsonc
9 
10### "waitForEvent Timeout"
11 
12**Cause:** Event not received within timeout period (check docs for default/max)  
13**Solution:** Wrap in try-catch to handle timeout gracefully and proceed with default behavior
14 
15### "Non-Deterministic Step Names"
16 
17**Cause:** Using dynamic values like `Date.now()` in step names causes replay issues  
18**Solution:** Use deterministic values like `event.instanceId` for step names
19 
20### "State Lost in Variables"
21 
22**Cause:** Using module-level or local variables to store state which is lost on hibernation  
23**Solution:** Return values from `step.do()` which are automatically persisted: `const total = await step.do('step 1', async () => 10)`
24 
25### "Non-Deterministic Conditionals"
26 
27**Cause:** Using non-deterministic logic (like `Date.now()`) outside steps in conditionals  
28**Solution:** Move non-deterministic operations inside steps: `const isLate = await step.do('check', async () => Date.now() > deadline)`
29 
30### "Large Step Returns Exceeding Limit"
31 
32**Cause:** Returning data exceeding the per-step return size limit  
33**Solution:** Store large data in R2 and return only reference: `{ key: 'r2-object-key' }`. Alternatively, return a `ReadableStream<Uint8Array>` for large binary output
34 
35### "Step Exceeded CPU Limit But Ran for a Short Time"
36 
37**Cause:** Confusion between CPU time (active compute) and wall-clock time (includes I/O waits)  
38**Solution:** Network requests, database queries, and sleeps don't count toward CPU. The CPU limit refers to active processing time only
39 
40### "Idempotency Violation"
41 
42**Cause:** Step operations not idempotent, causing duplicate charges or actions on retry  
43**Solution:** Check if operation already completed before executing (e.g., check if customer already charged)
44 
45### "Instance ID Collision"
46 
47**Cause:** Reusing instance IDs causing conflicts  
48**Solution:** Use unique IDs with timestamp: `await env.MY_WORKFLOW.create({ id: \`${userId}-${Date.now()}\`, params: {} })`
49 
50### "Instance Data Disappeared After Completion"
51 
52**Cause:** Completed/errored instances are automatically deleted after the retention period (differs by plan)  
53**Solution:** Export critical data to KV/R2/D1 before workflow completes
54 
55### "Missing await on step.do"
56 
57**Cause:** Forgetting to await step.do() causing fire-and-forget behavior  
58**Solution:** Always await step operations: `await step.do('task', ...)`
59 
60### "Provided event type is invalid"
61 
62**Cause:** Using unsupported characters in `waitForEvent` type (e.g. `.`)  
63**Solution:** Type only supports letters, digits, `-`, and `_`. Pattern: `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`
64 
65## Limits & Pricing
66 
67Limits and pricing change over time. **Always fetch the latest values** from the official docs before citing specific numbers:
68 
69- **Limits:** https://developers.cloudflare.com/workflows/reference/limits/
70- **Pricing:** https://developers.cloudflare.com/workflows/reference/pricing/
71 
72Key areas to check: CPU time per step, max steps per workflow, concurrent instance limits, step return size, event payload size, instance creation rate, subrequest limits, state retention period, and name/ID length constraints.
73 
74**Behavioral notes** (stable, not subject to number changes):
75- `step.sleep()` and `step.waitForEvent()` don't count toward the max steps limit
76- Instances in `waiting` state (sleeping, waiting for event, waiting for retry) don't count toward the concurrent instance limit
77- CPU time is active processing only — network I/O, DB queries, and sleeps are wall-clock time, not CPU time
78- `waitForEvent` type and workflow/instance names follow pattern `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`
79 
80## References
81 
82- [Official Docs](https://developers.cloudflare.com/workflows/)
83- [Get Started Guide](https://developers.cloudflare.com/workflows/get-started/guide/)
84- [Workers API](https://developers.cloudflare.com/workflows/build/workers-api/)
85- [REST API](https://developers.cloudflare.com/api/resources/workflows/)
86- [Examples](https://developers.cloudflare.com/workflows/examples/)
87- [Limits](https://developers.cloudflare.com/workflows/reference/limits/)
88- [Pricing](https://developers.cloudflare.com/workflows/reference/pricing/)
89 
90See: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)
91