What does Miiwa record when a Miiwa Agent run fails?
A failed Miiwa Agent run is a persisted session with version, trigger, status, timing and error context, supported by ordered execution events for diagnosis and recovery.
When a Miiwa Agent fails, the error is not the whole record. Miiwa persists the run session and its execution events so an authorised user or operator can distinguish a bad workflow assumption from a transient provider problem, a timeout or an exhausted retry budget.
Which evidence layers does a run leave?
| Layer | What Miiwa records |
|---|---|
| Run session | Workspace, deployment, version, workflow, user, trigger, status, title, input and output state, current block, error and timing. |
| Run events | Ordered lifecycle and block events with severity, timestamps and bounded event payloads. |
| Run steps | Where the execution path creates step rows, block-level input, output, status, error and duration. |
| Dead letter | For terminal queued-run failure, the session, deployment, trigger, attempt number and error needed for controlled replay. |
How does the event trail explain the failure?
The native event recorder stores workflow events against the session. Block starts, outputs, pauses, contract issues and errors can therefore be placed in execution order. Error events are marked at error level; pause events are warnings rather than terminal failures.
The replay reader loads the session only inside the requested workspace, then orders steps by their graph execution index and events by creation time. Events without a step remain visible as session-level or orphan events, which matters for direct assigned runs that do not create step rows.
Which failures does Miiwa retry automatically?
The queued runtime uses a bounded attempt budget and only requeues failures that look transient: timeouts, rate limits, temporary provider unavailability, selected server errors and network interruptions. Configuration and validation errors do not earn automatic retries because the same workflow would fail again and consume more time or AI budget.
A retry releases the claimed session back to the queue while preserving its error context. The next worker claim advances the attempt count. Once the configured budget is exhausted, the run can move to the dead-letter queue for an operator decision.
What happens in dead-letter replay?
An Admin can list unreplayed dead letters only within the active workspace. Replaying one resets the original session to queued, clears its terminal error and claim state, gives it a fresh attempt budget and marks the dead letter with the replaying user and optional note.
Miiwa rejects a second replay of the same dead letter and writes an audit event for the accepted replay. Replay is therefore a controlled operational action, not a hidden loop that keeps spending until something works.
How are pauses, timeouts and cancellation different?
- Paused
- The workflow reached a human-input or approval boundary. Miiwa persists its current block and variables so the same session can continue.
- Timed out
- The workspace run limit expired. Miiwa marks the session as error and signals the engine to stop at its next abort checkpoint.
- Cancelled
- An explicit stop changes the persisted run state; the executing route polls that state and aborts further work when it sees the run is no longer running.
- Dead-lettered
- A queued run reached a terminal failure and now requires an authorised replay decision.
An operator playbook for a failed run
- Open the workspace-scoped run and identify the deployment, version, trigger and final status.
- Find the last successful event and the first error or contract issue.
- Decide whether the cause is transient infrastructure, missing integration, invalid input or workflow configuration.
- Do not replay a deterministic failure until the workflow, connection or input has changed.
- Use Admin dead-letter replay only when the original external effects are understood and repeating the run is safe.
- Record the operational decision and feed recurring failure categories back into the next workflow version.
Miiwa treats failure as persisted operational state: diagnose from the workspace-scoped session and event trail, retry only transient errors and reserve dead-letter replay for an audited Admin decision.
Common questions
- Does Miiwa automatically retry every failed agent run?
- No. Automatic requeue is reserved for failures that match transient infrastructure or provider conditions and remains bounded by an attempt budget. Deterministic workflow and validation errors should be fixed before another run.
- Can any workspace user replay a dead-lettered run?
- No. Dead-letter replay requires Admin access, is scoped to the active workspace and creates an audit event with the replaying user.
- Is a paused Miiwa Agent considered failed?
- No. Paused is a distinct persisted status. The run keeps its current block and variables so an authorised user can supply input or approval and resume the same session.