Debug a failed workflow run

Inspect Diagnostics, Runs, variables, schema errors, and rerun options when a workflow fails.

This guide shows how to investigate a workflow run that failed, produced the wrong output, or behaved differently than expected.

What You'll Do

You will:

Find the failed run.
Identify the first failed step.
Compare step inputs, outputs, and variables.
Fix the workflow draft.
Rerun safely.

When to Use This

Use this whenever a workflow:

Fails during a manual, trigger, agent-tool, nested, or bulk run.
Produces an unexpected field value.
Cannot resolve a Liquid variable.
Returns invalid structured AI output.
Works in a test but fails when called by a trigger or agent.

Estimated time: 10-20 minutes.

Concepts used: Workflows, Tasks, Variables, Triggers.

1. Open the Failed Run

Start from the place where you noticed the failure:

Workflow builder: open the workflow, then the Runs tab.
Batch History: open the batch, then choose the failed item.
Trigger detail page: open the trigger's Runs tab.
Agent trace: open the workflow execution linked from the tool call.

Open the run and find the first failed step. Fix the first failure before chasing downstream errors because later steps often fail only because an earlier output is missing.

2. Inspect Step Inputs and Outputs

For the failed step, compare:

Inputs: what values the step received.
Configuration: the task settings saved on the workflow.
Outputs: what the step returned before failing, if anything.
Error: the exact failure message.

Common findings:

An input is blank because it was never mapped.
A variable path points to the wrong step number.
A task expects an account id but received a contact id.
An AI Prompt returned text when a later step expected JSON.
A side-effect task ran in a real environment during a test.

3. Check Variables in Diagnostics

Open the Diagnostics tab in the workflow builder. Diagnostics can catch:

Invalid Liquid syntax.
References to missing inputs.* values.
References to missing steps.* outputs.
AI output schema issues.
Broken mappings after a task was moved, removed, or changed.

If the failing value came from a prior step, inspect that prior step's output and update the downstream reference.

4. Confirm the Caller Mapped Inputs Correctly

Workflows can be called by triggers, agents, parent workflows, and manual runs. Each caller maps values into the workflow's declared inputs.

Check the caller:

Trigger: open the trigger assignment and confirm trigger outputs map to required workflow inputs.
Agent tool: inspect the tool call inputs in the agent trace.
Nested Workflow / For Each: inspect the parent workflow's task config.
Manual run: confirm the test runner values are realistic.

The old implicit {{trigger.*}} namespace is not used. Trigger outputs must be explicitly mapped to workflow inputs.

5. Fix the Draft

Make the smallest fix that addresses the first failure:

Correct a variable reference.
Add a missing input mapping.
Narrow an AI Prompt output schema.
Add an Update Record field mapping.
Change a task config value.
Split a large ambiguous step into smaller steps.

After you save, the change is a draft. Publish only when you are ready for triggers, agents, and manual runs to use the new version.

6. Rerun Safely

Choose the safest rerun option:

Rerun from failed step when prior steps succeeded and do not need to run again.
Rerun the whole workflow when the fix changes earlier inputs or task outputs.
Rerun failed items from Batch History when a bulk run partially failed.
Run a manual test first when side-effect tasks are involved.

Be careful with side-effect tasks like Send Email, Slack Message, Sanity Publish Document, Instantly Sequence, and record updates. A rerun can perform the side effect again.

Success Check

You are done when:

The rerun completes.
The expected record fields, integration side effects, or workflow outputs are present.
Diagnostics no longer show unresolved variables or schema errors.
If it was a batch, failed item count reaches zero or only expected/skipped failures remain.

Common Pitfalls

Debugging the last error instead of the first failed step.
Fixing a draft but forgetting to publish before testing from a trigger or agent.
Rerunning a workflow with side-effect tasks without checking whether the side effect already happened.
Updating a workflow input without remapping triggers, agents, or parent workflows that call it.
Copying a variable path by hand instead of using the variable picker.