Skip to navigation
Troubleshooting & FAQ

Flow execution failures

Use the Logs page to find the failed step, inspect its data, and verify a fix.

Identify a failed execution

Use the Logs filters and execution details to locate the failure. Follow these steps:

  1. Open Logs.
  2. Set Status to Failed.
  3. Select the failed entry.
  4. In Timeline, select the step with an error.
  5. In the inspector beside the timeline, review the step’s input, output, configuration, and error details.

A failed step doesn’t always fail the whole run. New steps use Continue on error, and Run Task and Run Agent steps continue after most errors. The run then finishes with the Completed status, and the Flow’s Runs view shows it as Completed with errors. The failed step’s own entry still appears in Logs when you set Status to Failed or show only the ERROR level.

If the inspector doesn’t show inputs, outputs, token counts, or costs, verbose logging was off when the execution ran. The detail view then shows Verbose logging off. Turn verbose logging on, then run the Flow again. For where to set it, see Verbose logging.

Find failures from code

When you run Flows from the API, the CLI, or an MCP client, you can find failures without the dashboard. When a step fails, a streamed dispatch sends a step_complete event with success set to false and the error message in error. When the Flow stops, the stream ends with an execution_error event. To list a Flow’s failed runs from the CLI, run this command:

runtype logs list --flow YOUR_FLOW_ID --status failed

Replace YOUR_FLOW_ID with the ID of the Flow. For live logs and the MCP tools, see Debug from code.

Diagnose common failures

Match the error to its step type, then apply the relevant check.

Model or prompt step error

A Run Task or Run Agent step fails when the model call fails. Check the error message against these causes:

  • Platform credit is exhausted. This error stops the Flow whatever the step’s error handling. To restore access, set a default payment method in Settings > Billing, or add your own provider API keys in Settings > Models > Providers.
  • The provider API key is invalid. Verify the key in Settings > Models > Providers.
  • The provider rate limit is reached. Add a Retry fallback with a Delay.
  • The model isn’t available. Select a configured model, or add a Different model fallback. For details, see Model not available.
  • The input exceeds the model’s context length. Shorten or summarize the input, or select a model with a larger context length.

For fallback types and triggers on prompt steps, see Handle errors.

Invalid JSON

If a request body or Run Code step reports invalid JSON, inspect the string that the step parses and the body that the HTTP step sends. Validate the JSON syntax, quote string values, and remove trailing commas. In a Run Code step, use JSON.parse to read a JSON string and JSON.stringify to serialize an object.

Missing input

When a required input is missing, compare the execution input with the fields that the Flow references. Check the spelling of each outputVariable. Confirm that the step that produces it runs before the reference. Add a validation step for values that must exist.

Use the following Run Code script to validate a required input:

if (!input.customer_id) {
  throw new Error('Customer ID is required')
}
return { validated: true }

Replace customer_id with the required input field. Choose Stop on error when a missing value must stop the Flow.

HTTP request failure

If Fetch URL or Make API Call returns an HTTP error, inspect the status, URL, method, headers, request body, and response format. Check these settings:

  • Verify that the endpoint and method match the external API.
  • Verify that authentication headers use the required secret or API key.
  • Confirm that the response format matches the value that the next step expects.
  • For an HTTP 500 response or a rate-limit response, review the external service response, then retry the request with a fallback.

To retry a failed request, click the error-handling control on the step card and select Use fallbacks. Add a Retry fallback, and set its Delay in milliseconds to give the service time to recover. Fallbacks run in order until one succeeds. For all error-handling modes, see Error handling.

Record not found

Get Record returns one Record and fails when no Record matches. List Records returns an array. With the default If no records match value of Succeed with an empty list, List Records returns [] when no Record matches. To fail the step on an empty result, set If no records match to Fail the step.

Check these values when a Record lookup fails:

  • Verify the Record ID, Record type, Record Name, filter, and lookup value.
  • Use Get Record when no match must fail the Flow.
  • Use List Records when no match is expected. Then check {{RECORD_MATCHES.length}} > 0 in a Conditional Logic step.

Replace RECORD_MATCHES with the Output variable name for the List Records step.

Run Code error

If Run Code reports a JavaScript error such as ReferenceError, check variable spelling, variable scope, and null or undefined values. Declare local variables with const or let, and return a value from the script.

Timeout

The default step timeout is 5 minutes, and the default Flow timeout is 15 minutes. The shortest applicable budget stops the run first. An Execute Agent step defaults to 30 seconds, and the whole-agent budget defaults to 5 minutes. Compare the failed step’s duration with its timeout value in Logs.

If the work needs more time, reduce the work or raise the timeout:

  • For an Execute Agent step, set Timeout (ms) on the step. The step still stops at the step timeout or the Flow timeout if either is shorter.
  • For a dispatched run, raise options.stepTimeoutMs or options.flowTimeoutMs in the dispatch request.

For limits by entry point and patterns for longer work, see Timeouts and long-running work.

Debug and verify a fix

Use a test run to reproduce the failure with controlled input. Follow these steps:

  1. In the Flow editor toolbar, click Run flow.
  2. In the Run Flow sheet, choose Test.
  3. Enter the input values for the Flow.
  4. To include outputs from hidden steps, open the execution mode menu and choose Run in debug mode.
  5. Click Run Flow.
  6. Review each step’s input, output, status, and execution time when available.

To rerun one step with the data from the Flow’s last run, run the Flow once. Then hover over the step and click Test step with last run. A step that writes Records, sends a message, or calls an external service repeats that action, so the dashboard asks you to confirm first. For details, see Retest one step.

To inspect intermediate values, add a Run Code step that returns the values you want to review. The execution results show the returned output.

After you fix the problem, save the Flow and run the test again. Products, Surfaces, schedules, and dispatch calls that don’t pin a version run the saved Flow as soon as you save. Publish to record a version that you can pin or roll back to. For more information, see Flow versioning and publishing.

Prevent and handle expected failures

Some failures are valid branches instead of defects. Use these practices to make Flow inputs and outputs explicit and to handle expected failures:

  • Fix each warning that validation reports when you save the Flow. For what each warning means, see Flow validation warnings.
  • Validate required inputs at the start of the Flow, and return a clear validation message for invalid input.
  • Check for null and undefined before you access properties.
  • Check HTTP status codes and expected response fields before you use response data.
  • For a missing Record, return a default or create a Record when appropriate.
  • When a step can fail without ending the Flow, keep Continue on error and handle its missing or default output in a later step.
  • Test empty inputs, null values, invalid data, API failures, and missing Records.

Next steps

Continue with these guides: