Skip to content

docs: Expand troubleshooting event types for root cause diagnosis #184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bchampp merged 1 commit into from
May 15, 2026
Merged

docs: Expand troubleshooting event types for root cause diagnosis #184

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion aws-lambda-durable-functions-power/steering/troubleshooting-executions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,32 @@ Steps:

2. If the command succeeds, analyze and provide a user-friendly diagnosis:
a. Report the execution status (RUNNING/SUCCEEDED/FAILED/STOPPED/TIMED_OUT)
b. Identify the root cause:
b. Identify the root cause by looking for these key events in the history:

**Execution-level failures:**
- `ExecutionFailed` — entire execution crashed; extract the error and cause fields
- `ExecutionTimedOut` — the execution exceeded its configured timeout
- `ExecutionStopped` — execution was manually stopped via StopDurableExecution

**Context and step failures:**
- `ContextFailed` — a child context threw an unhandled error; check the parent context for what triggered it
- `StepFailed` — an individual step failed; includes RetryDetails (CurrentAttempt, NextAttemptDelaySeconds) showing retry state

**Callback issues:**
- `CallbackStarted` with a Timeout field — confirms a timeout was registered; correlate with any subsequent `CallbackTimedOut`
- `CallbackTimedOut` — a timeout fired but may not have been caught by the function code
- `CallbackFailed` — the callback was resolved with an error

**Chained invocation failures:**
- `ChainedInvokeFailed` — a chained (child) durable execution failed
- `ChainedInvokeTimedOut` — a chained execution exceeded its timeout
- `ChainedInvokeStopped` — a chained execution was stopped

**Other signals:**
- `WaitCancelled` — a scheduled wait was cancelled before completing
- `InvocationCompleted` with an Error field — the Lambda invocation itself errored (e.g., runtime crash)

**Diagnosis patterns:**
- Failed operations: Show the EXACT error message verbatim in a code block
- Stuck in WAIT_FOR_CALLBACK: Extract callback ID, show how long it's been waiting
- Timeout: Show which operation was running when timeout occurred
Expand Down