Handling batch failures

When Records fail in a batch, find the failed Records, fix the Flow or the Records, and run the batch again.

Before you begin

Run a batch on a Flow. For instructions, see Running flows in batch.

Identify failures

Where you inspect failures depends on how the batch started.

To find failed Records in a batch that a Schedule started, follow these steps:

1. On the Schedules page, open the Schedule.
2. On the Runs tab, click the run. The batch results open.
3. In the status filter, select Failed.
4. Optional: To find one Record, click Find a record and enter its Record ID.
5. On a failed row, click the details icon (View details).

The detail panel shows the Record metadata, output, per-step results, and error for that execution. The results header shows how many Records finished with failed steps.

To find failed Records in a batch that you started from the Flow editor or through the API, follow these steps:

1. Open Logs.
2. In Type, select Batch.
3. Review the entries for failed Records. Each entry names the Record’s position in the batch and its error.

A Record whose Flow finishes with failed steps does not get a failed Batch entry. To find these Records, select Flow in Type and review the step results of each Flow execution.

Read the error

Each failed row shows one of the following kinds of error:

• The error that stopped the execution, such as a timeout or a provider error.
• Flow completed with one or more failed steps. The Flow finished, but at least one step failed and was set to continue. To see that step’s error, open the row’s details and check the per-step results.

Common failure types

Use the following table to choose a fix for the error on a failed Record.

If the batch does not start

A batch can be rejected before any Record runs. The dashboard shows the error in a notification, and the API returns it in the response.

Check failures with the API or CLI

If you started the batch through the API, an SDK, or the CLI, use these calls to check it:

• GET /v1/batch/status/{id} returns the batch status, processedRecords, and failedRecords.
• GET /v1/batch/{batchId}/records/{recordId}/steps returns the step results for one Record, ordered as a timeline.
• runtype batch status BATCH_ID --watch polls the batch until it finishes, or until the watch timeout (5 minutes by default) passes. Replace BATCH_ID with the batch execution ID.

For request and response details, see the Batch entries in the API reference.

Stop a failing batch

If most Records are failing, cancel the batch before you fix the Flow. This stops spending on a broken run. The dashboard does not have a cancel control, so use one of these options:

• Run runtype batch cancel BATCH_ID.
• Call POST /v1/batch/cancel/{id}.

Records that did not finish fail with Batch was cancelled. To copy the batch ID, click the batch ID in the batch results header, or copy the Batch field of a batch entry in Logs.

Rerun a batch after a fix

A batch retries a Record whose execution fails with an error, such as a timeout or a step set to Stop on error. A batch that you start from the Flow editor retries the Record up to 5 times before it marks the row Failed. A batch that the API or a Schedule starts retries up to 3 times by default. To change this, set options.maxRetries (0 to 10) when you start the batch through the API. A Record whose Flow finishes with failed steps is not retried.

To rerun the batch for the same Record type, follow these steps:

1. Fix the Flow logic or correct the affected Records on the Records page.
2. In the Flow editor, click Run flow.
3. Select the Batch tab.
4. Select the same Record Type.
5. Click Run on Records.

To publish the Flow change, click Publish after you test the batch.

The dashboard reruns every Record of the type. To rerun only the failed Records, submit their Record IDs in recordIds through the batch API. For details, see Running flows in batch.

Handle failures inside a Flow

By default, a Run Code step continues after a script error. The step stores its default value, the Flow keeps running, and the batch marks the Record as completed. The script error appears only in the per-step results. To make a script error fail the Record, set the step to Stop on error. For details, see Handle errors.

To route invalid input yourself, return a structured result from the Run Code step:

try {
  const parsed = JSON.parse(input.raw_data)
  return { success: true, data: parsed }
} catch (error) {
  return { success: false, error: error.message }
}

Replace raw_data with the output variable of the earlier step that contains the JSON text.

Use a Conditional Logic step to branch on the success field and route invalid Records to an error path. On prompt steps, select Use fallbacks to retry the same model, use a different model, or return a fixed message when the configured trigger fires.

Debug an individual failure

To investigate one failed Record, follow these steps:

1. In the batch results, click the details icon (View details) on that row.
2. Review the Record metadata, output, per-step results, and error.
3. To see the run history for each Record, click Record runs in the batch results header. Alternatively, open Logs and select the execution to inspect its timeline and step details.

For filtering and inspecting execution history, see Working with logs.

Prevent failures

Use these practices before you scale a batch:

• Validate inputs: Add validation or default handling near the start of the Flow.
• Handle step errors: Use try/catch in Run Code steps and branch with Conditional Logic.
• Configure prompt fallbacks: Add a different model for rate limits and slow model calls.
• Test edge cases: Run a small batch against Records with missing or malformed data.
• Review limits: Check provider rate limits, your spend cap, and available credit before starting a large batch.

Next steps

Continue with these guides:

• Running flows in batch: learn to start and monitor a batch.
• Timeouts and long-running work: set batch, Flow, and step timeouts.
• Debugging flows: inspect Flow steps and execution errors.
• Using prompt steps: configure prompt error handling and fallbacks.
• Automating batch processing: schedule batches with Schedules.