Inspect and troubleshoot a failed Workflow run

Use this procedure when a Workflow run is Failed, remains Queued unexpectedly, or completed through an error route without producing the expected business result.

1. Start with the run, not the final provider symptom

Open the Workflow, select Audit, and open the affected run. Record the run ID, status, timestamps, attempt count, Workflow version, and top-level error before changing configuration or replaying anything.

Confirm that you selected the correct run by comparing a stable Trigger field such as provider event ID, order ID, issue ID, or request timestamp.

2. Verify Trigger evidence

Inspect the Trigger preview and answer:

• Did the expected Source create the run?
• Does the payload represent the correct provider event and action?
• Are the fields used by Filters, Paths, mappings, and transformations present?
• Is the preview missing because of retention or storage state, or was the input itself empty?

A missing preview is not proof that no event was accepted. Correlate it with Source or Activity evidence.

3. Find the first failed Step

Read Steps in execution order. The first failed Step is normally the cause; later skipped Steps are consequences. Inspect its kind, selected input route, mapped input, response status, public error code, message, retryability, and attempt.

The Step timeline keeps the failure beside its input route and execution evidence. Diagnose this first failed card before treating later skipped Steps as separate failures.

Common classifications:

• Mapping or validation: a required value is empty, has the wrong type, or came from the wrong ancestor.
• Authentication or permission: the connected account was revoked, lacks a scope, or cannot access the selected resource.
• Provider resource: a channel, spreadsheet, repository, record, or other target was deleted or renamed.
• Rate limit or temporary provider failure: the error may be retryable or include provider retry timing.
• Transformation: input shape differs from the tested sample or a JSON Patch path does not exist.
• Routing: the expected Path did not match and its Step is Skipped rather than Failed.

4. Check retry and error-route state

Do not manually repeat a side-effecting Action while an automatic retry is pending. A run can be Queued because of retry timing or an active Delay.

If the failed Step has an Error route, inspect that branch separately. A run may finish successfully after recovery while retaining the failed Step. If no route handles a terminal failure, the run becomes Failed and unreachable Steps are skipped.

Queue exhaustion is terminal and appears as workflow_delivery_exhausted; it also closes pending or running Step records.

5. Fix with a controlled event

Make the smallest change supported by the evidence: correct one mapping, reconnect one account, select a valid resource, narrow one Trigger, or update one error route. Save the Workflow, produce a new controlled event, and compare the new run with the failed run.

Only replay or repeat a side-effecting operation after checking whether the provider already accepted it. Use provider idempotency controls and stable event IDs where available.

Incident handoff checklist

Capture the run ID, Workflow/version, Source event ID, first failed Step, sanitized mapped input, response status, public error code, attempt count, and whether an automatic retry or recovery Action ran. Do not paste access tokens or raw secrets into tickets.

See Runs and errors, Error handling, Data mapping, and Connected accounts.