Debug Failed Jinba Flow Runs

Find the first failing step, inspect its inputs and outputs, and test a fix.

Start with the run that failed. Find the first step marked as failed, then inspect its inputs, output, and error details before changing the flow.

Open a run to inspect its inputs, step outputs, and errors

Inspect a failed run

1. Open the flow’s run history and select the failed run.
2. Find the first failed step. Steps that need it are marked cancelled, not failed, so fix the first failure before looking at them.
3. Review the step’s inputs, output, and error message.
4. Compare each input name and value with the selected tool’s documentation.
5. Correct the flow and run it again.

A step error has a name (such as StepTimeoutError), a message, and, when available, a stack trace.

Step statuses

Status	Meaning
success	The step finished
failed	The step raised an error
cancelled	A step in its needs failed or was cancelled, so it did not run
skipped	Its when condition was false, or every step in its needs was skipped

For a forEach step, each item has its own status. The step as a whole is partial when some items failed and others succeeded.

Run a flow with test inputs, then open the result details

Test one step

Use Run Step on a step to test that step without running the entire flow. If the flow has unsaved changes, use Save & Run Step.

• The step reads earlier steps’ results from the latest completed full run. If you ran an earlier step on its own after that, its newer result is used.
• If the flow has never completed a full run, references to earlier steps resolve to empty values. Run the whole flow once first.
• The step runs even if its when condition is false or a step in its needs failed, and it is not retried.

After the step runs, inspect its result in the run details. The shape of result depends on the tool; use that tool’s documentation to confirm the fields you can reference.

Troubleshoot common failures

The flow does not validate

• Check that each step has a unique ID and a valid tool ID.
• Check that each tool step has an input list, even if it is empty.
• Compare input and configuration names with the selected tool’s documentation.
• Check YAML indentation and step references.

Common validation messages:

Message	Cause
Duplicate step IDs found in flow	Two steps share an id
Flow contains circular dependencies	Steps need each other in a loop
Tool not found: <TOOL_ID>	The tool value is not a tool ID
Invalid config or input for tool "<TOOL_ID>": ...	An input or config value is missing or has the wrong type; the rest of the message names the field
Invalid step references: ...	A template refers to a step that does not exist, a field that the tool’s output never includes, item outside a forEach step, or a step result inside config

See Write a YAML manifest for the manifest structure.

A step fails immediately

• Read the error shown for that step.
• For an integration step, check its credential and the permissions granted to that credential.
• Confirm required inputs are present and have the expected type.
• If the error comes from an external service, check that service’s response and status, including rate limits.
• Step '<step_id>' timed out after <N>ms means the step ran longer than its time limit.

A step is skipped or cancelled

• cancelled: find the failed step it needs and fix that step first.
• skipped: check its when condition against the actual output of the steps it refers to. With {{ }} placeholders, the text is filled in before evaluation, so quote text values: "'{{ steps.check.result.type }}' == 'premium'".
• Failed to evaluate when condition on step '<step_id>' means the condition could not be evaluated, often because it refers to a field that the result does not have. The step is marked failed.

A later step cannot find a value

• Confirm the referenced step ID matches the manifest exactly.
• Check the prior step’s actual output; tools return different result shapes.
• Add the prior step ID to needs. A reference alone does not make a step wait, and a missing value becomes an empty string instead of an error.
• Use the supported reference form, such as {{ steps.fetch.result }}.

A step produces unexpected output

• Compare the inputs shown for the step with what you expected; objects and arrays are inserted as JSON text.
• Check the tool’s configuration and documentation.
• Run the step again with Run Step after each change.

Share a useful error report

When asking for help, include the flow ID, run ID, failed step ID, the exact error message, and the relevant input/output shape. Remove API keys, tokens, and private data first.