Flows and runs
Fixing a flow run that stopped. A run that failed, a checkpoint waiting on you, a run blocked on something outside it, a run interrupted by an update, and the daily run and compute limits.
Open the run, read the step that stopped, and the state tells you the move. A flow run moves through a clear set of states, and when it stops, the state is the reason. This page covers the reasons a run stops and the fix for each. For the full vocabulary first, the statuses reference lists every run and step state.
A run failed (failed status)
What you see. The run shows failed, and the step timeline marks one step as failed in red. The failed step carries an error message, and its transcript holds everything the agent did up to the point it stopped.
Why it happens. A step fails for one of a few reasons, and the failed step's error names which: the agent hit an error while working, a step that builds or checks the work reported it did not pass, or a step reported its own result as an error rather than a success. By default a failed step stops the run rather than pressing on, which is what surfaces the failure to you instead of burying it. A step can be set to skip or fall back instead, but the default is to stop.
How to fix it. Read the failed step's error and its transcript to see what happened. Once the cause is addressed, retry the run. A retry starts again from where it stopped, on a fresh sandbox if the previous one cannot be reused, so you do not repeat the steps that already succeeded. If the failure was in the work itself rather than the run, the fix is usually to adjust the plan or the skill the step runs and retry from there.
A checkpoint is waiting
What you see. The run shows paused, and the step timeline stops in front of a step with an approval waiting. The checkpoint can carry a message explaining what it wants you to review.
Why it happens. This is not a failure. A checkpoint is a step the Flow marks for a person to approve before it runs, which is how a run keeps a human in the loop at the moments that matter. The run is doing exactly what it was told: holding for your decision. A background run pauses at a checkpoint the same way, unless that step was set to approve on its own in the background.
How to fix it. Open the run and make the call. You have three moves:
- Approve lets the step run and the rest of the flow continue.
- Reject ends the run. Its status becomes rejected, which is an intentional stop you chose, not an error. Use it when the work so far is not what you want.
- Skip passes over the waiting step and moves to the next one.
A run only ever pauses for a checkpoint; there is no other condition that pauses one. If a background run has been paused for a while, it is waiting on this decision and will keep waiting until you make it, so a paused background run is a prompt for you, not a stall. For how a background run surfaces its checkpoint and where the decision appears, see run a Flow.
A step shows as skipped
What you see. The run completed, but one step in the timeline is marked skipped rather than completed, and you expected it to run.
Why it happens. A step can carry a condition that decides whether it runs, so a step is skipped on purpose when its condition does not apply this time, for example a "fix the review comments" step that runs only when a review found something to fix. A skipped step is not an error and does not mean the run is incomplete; it means the run did exactly what its conditions told it to.
How to fix it. If the step should have run, the condition is the thing to look at. Open the Flow and check the step's condition against what the earlier steps actually produced, since a condition compares a previous step's output and skips when it does not match. Adjust the condition or the upstream output, then run the Flow again.
A run is blocked
What you see. The run shows blocked, with a note about what it needs. The common cases are a credential to reach a repository, a connected tool the run could not reach, and an environment with an open issue that the work depends on.
Why it happens. A blocked run has hit something outside the agent that has to be resolved before it can safely continue, so it parks instead of pushing on. There are three common causes, and the note on the run names which one you have: a credential the run needs to reach a repository, a connected tool the run could not reach, or an environment with an open issue the work depends on.
How to fix it. Clear what the run named, then resume. The run rechecks and continues from the blocked step once nothing is still blocking.
- A credential block. The run needs access to a repository it could not reach, usually because a connection needs to be authorized or re-authorized. Authorize the repository's connection, then resume.
- A connected-tool block. An MCP server the run relies on could not be reached, or its sign-in has expired. Reconnect or re-authorize the server, then resume.
- An environment block. The platform raised a blocker on the environment the work targets, for a reason like infrastructure that needs to be in place, a database schema migration, a pipeline environment, a missing secret identity, or a capability the environment does not yet have. Resolve the open blocker on the environment, then resume.
The deeper fixes live on connections and access and sandboxes and hosts. For what an environment blocker is and what raises one, see sandboxes.
A run was interrupted by an update
What you see. The run shows interrupted by deploy.
Why it happens. The platform was updated while the run was in flight. Rather than let the run end in an unknown state, the platform stops it cleanly and marks it so you know exactly why it stopped. The sandbox it was using is kept.
How to fix it. Retry it. Because the sandbox was preserved, the run picks up from where it was rather than starting over, so an update that lands mid-run costs you a retry, not the work.
A run is stuck, or you want to stop it
What you see. The run shows running and has not advanced for longer than the work should take, or it is doing something you want to call off.
Why it happens. A long-running step is usually still working, since a single step can take many turns, so check the step transcript for recent activity before assuming it is stuck. A step that genuinely stalls is detected and retried on its own, unless it has an external side effect like opening a pull request, which is never auto-retried so it cannot happen twice.
How to fix it. Open the run and read the active step's transcript. If it is still taking turns, it is working. If you want to stop it regardless, cancel the run, which stops it and releases its sandbox, then retry once you have adjusted whatever sent it long.
A new run will not start (run or compute limit)
What you see. A new run will not start, and you are told you have reached a limit, either the number of flow runs for the day or the compute time available.
Why it happens. Each plan includes a number of flow runs per day and an amount of sandbox compute, and a run is checked against both before it starts. The daily run count resets at midnight UTC. The plans and quotas reference lists the exact numbers per plan, and the daily-run count covers every start, whether a person launched it or a trigger fired it.
How to fix it. If you have hit the daily run count, the count clears at the next UTC day, so the run can start then. If you need more headroom than your plan includes, use Request capacity to ask for a review. The same applies to compute: it is measured per UTC day and resets on the same clock. Scheduled and triggered runs count too, so if automatic runs are using up the day's allowance, narrowing a trigger's filters or pausing a schedule frees room for the runs you start by hand.
Recovering one run, start to finish
Sarah's nightly Full SDLC run on the CSV download button plan shows failed when she opens it in the morning. She does not start over. She opens the run.
The step timeline tells her the shape at a glance: Plan and Implement carry green checks, and Verify is marked failed in red. She selects the Verify step. Its error reads that two of the five customer fixtures did not pass, and its transcript shows the assertion that broke with the output underneath it. The code the Implement step wrote is still there, saved, with its diff in the transcript.
The cause is in the work, not the run, so she corrects the plan's expected output to match the fixed fixture and clicks Retry. The retry starts from Verify, the first step that did not complete, on a fresh sandbox. Plan and Implement are not run again. Verify passes, the Create PR step opens the pull request, and the run completes.
One read, one fix, one retry. Nothing before the failed step was repeated, and nothing was lost.
Why a stopped run holds its place
Every state on this page is recoverable for the same reason: a run keeps its position when it stops and nothing throws away the work that came before. So the loop is the same every time: open the run, read the step that stopped, resolve the named cause, and retry or resume.
For a prospect, the takeaway is that a run is safe to walk away from. It holds at a checkpoint, parks on a blocker, or stops cleanly on an update, and it is there with its reason when you come back.