Best Practices & Troubleshooting
Best Practices
1. Use Descriptive Event Names
Choose event names that describe what happened, not generic labels. Clear names make it easier to debug, trace, and document your workflow's event contract.
1// Good: Clear, descriptive names2ctx.wait_for_event("order_approved").await?;3ctx.wait_for_event("payment_confirmed").await?;4ctx.wait_for_event("shipment_delivered").await?;56// Bad: Vague names — impossible to debug7ctx.wait_for_event("event1").await?;8ctx.wait_for_event("done").await?;9ctx.wait_for_event("ok").await?;2. Always Use Timeouts for External Events
Any event that depends on an external system or human should have a timeout. Without a timeout, a lost webhook or forgotten approval blocks the workflow forever.
1// Good: Has timeout and fallback logic2let approval = ctx3 .wait_for_event_with_timeout("approve", Duration::from_secs(3600))4 .await?;56match approval {7 Some(data) => { /* Process approval */ }8 None => { /* Handle timeout — escalate, auto-approve, or fail */ }9}1011// Bad: No timeout — workflow hangs forever if event never arrives12let approval = ctx.wait_for_event("approve").await?;3. Type-Safe Event Payloads
Define structs for event payloads to catch schema mismatches at compile time rather than runtime. Avoid parsing raw JSON values manually.
1// Good: Strongly typed — compiler catches mismatches2#[derive(Deserialize)]3struct ApprovalEvent {4 approved: bool,5 approver_id: String,6 timestamp: DateTime<Utc>,7}89let event: ApprovalEvent = ctx.wait_for_event("approve").await?;1011// Bad: Untyped JSON — runtime panics on missing fields12let event: serde_json::Value = ctx.wait_for_event("approve").await?;13let approved = event["approved"].as_bool().unwrap(); // Runtime crash if field missing4. Handle Missing Events Gracefully
When using timeouts, always handle the None case explicitly. Use default behavior, escalation, or clean failure — never .unwrap() or .expect() on a timeout result.
1// Good: Explicit handling of timeout case2let event = ctx3 .wait_for_event_with_timeout("optional_event", timeout)4 .await?;56let result = match event {7 Some(data) => process_with_event(data),8 None => use_default_behavior(),9};1011// Bad: Panics if event times out12let event = ctx13 .wait_for_event_with_timeout("optional_event", timeout)14 .await?15 .expect("Event required!"); // Crashes on timeout5. Document Event Contracts
Document which events a workflow accepts, their payload types, and timeout behavior. This is the contract between the workflow and its callers — without documentation, event names and payloads become tribal knowledge.
1/// Order approval workflow2///3/// **Events accepted:**4/// - `approve` — Manager approval decision5/// - Payload: `ApprovalData { approved: bool, approver: String, reason: String }`6/// - Timeout: 24 hours (auto-escalates)7///8/// - `expedite` — Request expedited processing9/// - Payload: `bool`10/// - Optional, no timeout11#[workflow]12pub async fn order_workflow(13 ctx: WorkflowContext,14 input: OrderInput,15) -> Result<OrderResult> {16 // ...17}Troubleshooting
If events aren't behaving as expected, these are the most common issues and how to resolve them.
Event Not Delivered
Symptom: Workflow hangs waiting for an event that was sent.
Common causes:
- Event name mismatch — names are case-sensitive and must match exactly
- Wrong workflow ID — event sent to a different workflow instance
- Workflow not yet started — event sent before the workflow begins execution (events are buffered, but the workflow must exist)
Solutions:
- Verify event names match between sender and receiver
- Log the workflow ID on both sides and confirm they match
- Use event buffering — it's safe to send events before
wait_for_event()is called
Timeout Too Short
Symptom: Events arrive after the timeout expires.
Solutions:
- Account for network latency and processing time in timeout values
- Use longer timeouts for human interactions (hours/days) vs. system callbacks (seconds/minutes)
- Monitor event delivery latency to tune timeouts appropriately
Event Payload Errors
Symptom: Deserialization errors when receiving events.
Solutions:
- Ensure the sender's payload structure matches the receiver's expected type exactly
- Use the same serialization format (JSON) on both sides
- Add versioning to payload types if the schema evolves over time