# Handling failure

> Building flows · https://spoletta.com/docs/failures

Steps fail: an API is down, a fix doesn't pass its tests, an agent runs out of time. Spoletta lets you bound how long a step may take, try it again, and hand a failure to another process instead of failing the run.

*Diagram: Fix failed after its retries; Report handles it, and the run can still end done.*

## When a step fails

An agent, script or Sentry step fails on:

-   an error, or a script's non-zero exit;
-   a reply that doesn't match its output contract, after it was told what was wrong;
-   its timeout;
-   a person stopping it.

A failure **ends its branch**. The rest of the run goes on, but the run ends failed, unless a handler takes the failure.

## Timeout and retries

| Setting | Range | Effect |
| --- | --- | --- |
| Timeout (s) | 1 to 86400 | The step fails after this long. Empty uses the worker's. |
| Retries | 0 to 5 | How many more times a failed step is tried. Each try is a step of its own in the run's list. A stopped step isn't retried. |

## Failure handlers

1.  **Draw the connection**
    
    Drag from the process that may fail onto the one that handles it. The connection is red and dashed, *on failure*. Only agent, script and Sentry processes can have one, and a process can't handle its own failure.
    
2.  **Write the handler**
    
    The handler runs in a fresh pass and is given everything the failed process took, plus an extra input named `Failure of Fix` holding what went wrong. It needs no links of its own to receive them.
    
    Report's prompt:
    
    ```text
    Fixing this exception failed. Comment on the Sentry issue
    with what was tried and why it failed.
    ```
    
3.  **Carry on**
    
    The failed process's branch ends, but the run goes on and can still end done. The handler can yield what the branch would have, such as an item of Outcomes.
    

> **Watch out:** A step stopped by a person, or stopped with its run, is not handled.

## How a run ends

| Status | When |
| --- | --- |
| Done | Nothing is left to run and no failure went unhandled. |
| Failed | Some branch failed without a handler. |
| Terminated | A step generated a unique value another run already stored; reviews still waiting end undecided. |
| Interrupted | A person stopped the run, or the server restarted mid-run. |

OPL:

```text
Fix fails after 1800 seconds.
Fix is tried again up to 1 times when it fails.
Report handles a failure of Fix.
```

To find out why a step failed, see [Debugging a run](https://spoletta.com/docs/debugging.md).