Guides

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 names
2
ctx.wait_for_event("order_approved").await?;
3
ctx.wait_for_event("payment_confirmed").await?;
4
ctx.wait_for_event("shipment_delivered").await?;
5
6
// Bad: Vague names — impossible to debug
7
ctx.wait_for_event("event1").await?;
8
ctx.wait_for_event("done").await?;
9
ctx.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 logic
2
let approval = ctx
3
.wait_for_event_with_timeout("approve", Duration::from_secs(3600))
4
.await?;
5
6
match approval {
7
Some(data) => { /* Process approval */ }
8
None => { /* Handle timeout — escalate, auto-approve, or fail */ }
9
}
10
11
// Bad: No timeout — workflow hangs forever if event never arrives
12
let 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 mismatches
2
#[derive(Deserialize)]
3
struct ApprovalEvent {
4
approved: bool,
5
approver_id: String,
6
timestamp: DateTime<Utc>,
7
}
8
9
let event: ApprovalEvent = ctx.wait_for_event("approve").await?;
10
11
// Bad: Untyped JSON — runtime panics on missing fields
12
let event: serde_json::Value = ctx.wait_for_event("approve").await?;
13
let approved = event["approved"].as_bool().unwrap(); // Runtime crash if field missing

4. 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 case
2
let event = ctx
3
.wait_for_event_with_timeout("optional_event", timeout)
4
.await?;
5
6
let result = match event {
7
Some(data) => process_with_event(data),
8
None => use_default_behavior(),
9
};
10
11
// Bad: Panics if event times out
12
let event = ctx
13
.wait_for_event_with_timeout("optional_event", timeout)
14
.await?
15
.expect("Event required!"); // Crashes on timeout

5. 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 workflow
2
///
3
/// **Events accepted:**
4
/// - `approve` — Manager approval decision
5
/// - Payload: `ApprovalData { approved: bool, approver: String, reason: String }`
6
/// - Timeout: 24 hours (auto-escalates)
7
///
8
/// - `expedite` — Request expedited processing
9
/// - Payload: `bool`
10
/// - Optional, no timeout
11
#[workflow]
12
pub 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

Next Steps