# Debugging a run

> Running and debugging · https://spoletta.com/docs/debugging

Every step of every run keeps what it was given, what it did and what it handed back. When a run surprises you, the answer is almost always in one of its steps.

## Where problems show

-   On the board: a failed process turns **red**, a skipped one grey and dashed, and one that hit a duplicate purple.
-   In the process's settings panel: *Last run failed* in red, *Skipped*, or *Already processed; the run was terminated*, next to *Last run output*.
-   In the run panel: the step's red Error block.
-   Under the toolbar: a banner for a request the app couldn't carry out. Click it to dismiss it.

## Reading a step

Open the run, then the step. From top to bottom it shows:

| Section | What it tells you |
| --- | --- |
| Status and time | When it started, and the tokens and cost an agent used. |
| Model: … · thinking: … | Which model an agent ran on, and its pi session. |
| Worked on the branch | The git branch, and per repository the commits it made, from one commit to another, and whether it left changes uncommitted. |
| Input | Each object it took, in its state. For a review: what it reviewed and who marked it. |
| Prompt sent to the agent | The whole prompt as the engine built it (or *Script it ran*, *Request sent to Sentry*). Check here first when an agent misunderstood. |
| What the agent did | The live transcript: its thinking, each tool it called and what came back, and what it said. |
| Decision | For a human step: who decided, and what. |
| Error | Why it failed: the error, a script's stderr, a timeout. |
| Output | What it handed in, and each object it generated, in its state. |
| Files | Download links for the files it wrote. |

JSON is shown as fields, with **Raw** and **Formatted** to switch, and Markdown is rendered. A procedure's step says *Ran its board as run #N*; click it to open that run.

## Inspecting a process or object

While a run is shown, double-click any process or object to focus the run panel on it. For an object you see each value it took in the run, *made by* which step, its files, and which processes took it. For a process that didn't run, the panel says so, with **Show all** to go back to every step.

## Retries and re-asks

Two different things can look like “it tried again”:

-   **Retries** (set on the process) are steps of their own, so each try shows as a separate step in the list.
-   **Try N** inside one transcript means the agent didn't hand in its output in the right shape, so it was asked again within the same step.

## Common symptoms

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| An agent works on an empty input | Nothing generates the object it takes, so it exists empty from the start. | Have a person fill it in, or a script or Sentry step fetch it, before the agent. |
| A process never runs | It has an event link, so it runs only on its events; or it takes plainly the object it is meant to write. | Make it the start, or split it into a writer and a reviser that takes the object in the send-back state. |
| A join after a branch never runs | The branch not taken never generates its object. | Give the join a quorum (Needs) of 1, or build the branches with condition links. |
| A script’s output is in no state | Scripts and Sentry steps can’t decide states. | Add state rules to the object. |
| An object never reaches the last state | A state without a rule never matches, so a rule-less catch-all is never chosen. | Give the catch-all a rule that always holds. |
| A reviewer fails after a few rounds | It used up its rounds and sent work back again. | Raise Rounds, or add a failure handler to the reviewer. |
| Scheduled runs are skipped | The flow starts with a person, and the last run is still waiting for them. | Start a scheduled flow with a script or Sentry step. |
| A procedure doesn’t see the caller’s changes | A procedure runs in a workspace of its own, on its own branch. | Push or finish the work in the caller, and hand the procedure only what needs no checkout. |
| The run ends terminated | A step generated a unique value another run already stored. | Expected when deduplicating; otherwise check the Unique attributes. |
| Nothing runs at all | The Start node isn’t connected. | Drag from Start to the first process; the Run button stays disabled until then. |

## Check the OPL

Many mistakes show up before a run as a missing or surprising sentence. Open **OPL** and read it through:

OPL:

```text
The flow starts with Pick release.
Draft takes Release.
Pick release has a person fill in Release.
```

No *The flow starts with…* means no start. An agent that *takes* an object no sentence says is generated or filled in will get it empty. A process whose every input reads *entering … triggers* runs only on those events. When you have found the cause, fix the board and use [Re-run from here](https://spoletta.com/docs/reruns.md) rather than starting over.