> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Flow execution failures

> Diagnose and fix failed Flow executions with logs and test runs

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](/user-guide/logs/what-are-logs#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:

```bash
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](/user-guide/flows/debugging-flows#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](/user-guide/troubleshooting-faq/common-errors-and-solutions#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](/user-guide/flows/using-prompt-steps#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:

```javascript
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](/user-guide/flows/creating-and-editing-flows#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](/user-guide/flows/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](/user-guide/flows/debugging-flows#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 test that saved version. Publish it
to activate the fix. Products, Surfaces, schedules, and unpinned dispatch calls
keep using the existing publication until Publish succeeds. A Flow with no
publication, or a legacy publication created before this saved-version model,
uses its current saved definition until you explicitly publish. For more information, see
[Flow versioning and publishing](/user-guide/flows/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](/user-guide/flows/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:

* [Debugging flows](/user-guide/flows/debugging-flows): reproduce failures and inspect step results
* [Working with logs](/user-guide/logs/working-with-logs): filter and inspect execution details
* [Common errors and solutions](/user-guide/troubleshooting-faq/common-errors-and-solutions): fix specific error messages
* [Timeouts and long-running work](/user-guide/flows/timeouts-and-long-running-work): raise timeouts and split long work
* [Using Fetch URL and API call steps](/user-guide/flows/using-fetch-url-and-api-call-steps): configure HTTP requests
* [Using record steps (get/list/upsert)](/user-guide/flows/using-record-steps-upsert-retrieve):
  handle missing Record results
* [Handling batch failures](/user-guide/flows/handling-batch-failures): find and rerun failed Records in a batch
* [Agent execution failures](/user-guide/troubleshooting-faq/agent-execution-failures): diagnose failed Agent runs, stop reasons, and tool errors