Failed tasks and fix loops
The first column is the text the board and kraft view show ID print. ... stands for text that varies. A forge or git call that failed is on Forge stops.
Questions and failed tasks
| The reason says | What happened | Fix |
|---|---|---|
needs_context: <question> | The agent asked a question it couldn't answer from the repo. | Run kraft item resume ID --steer "<answer>". |
task failed in node <node>: ... | An agent task or command failed. | Read kraft view logs ID, then run kraft item retry ID --steer "<the fix>". |
task failed in node <node>: ..., and the log shows an authentication or login error | The agent CLI is installed but not signed in. | Sign in once in a terminal (claude for the shipped chains), then run kraft item retry ID. kraft admin doctor checks only that the CLI is on PATH. |
<scope> is read_only, but it changed the worktree: ... | A read-only step edited files. | Look at the named files, then run kraft item retry ID. |
Fix loops, gates and reviews
| The reason says | What happened | Fix |
|---|---|---|
<loop> exhausted after N fix cycle(s) | A fix loop spent its attempts without passing. | Read the findings with kraft view events ID --type findings_measured, then run kraft item retry ID --steer "...". |
<gate> exhausted after N rejection(s) | A gate was rejected as many times as its chain allows. | Run kraft item retry ID --steer "...", or rework the spec or plan yourself. |
stuck: ... or judge: ... | A fix loop made no progress across cycles (stuck), or the loop's judge decided another repair isn't justified (judge). Kraft has already tried an escalation turn. | Run kraft item escalate ID --message "...", or kraft item retry ID --steer "...". |
stuck: fix attempt N in node <node> changed nothing, ... Added in 2.6 | A repair changed no file (an empty commit counts as nothing), replied to no review thread and edited no merge request description, so measuring again would see the same code. | If the failure was flaky, run kraft item retry ID. Otherwise add --steer naming the fix; the reason holds the repair's concerns. |
a repair in node <node> finished with concerns ... | A repair ran, but its agent doubted the result. | Read the concerns in the reason, then run kraft item retry ID --steer "...", or kraft item skip ID. |
<node>.on_base_changed exhausted after N restart(s) from '<node>' | The base branch kept moving: each restart found it moved again. The shipped chain restarts merge_request_feedback from verification. | Run kraft item retry ID once the base branch settles; a retry resets the count. To allow more restarts, raise that key under loops: in policy.yaml. |
the merge request was closed on the forge without merging | Someone or something other than Kraft closed the item's merge request. The stop kind is mr_closed. | On the item's page, select Reopen !N. MR closed externally lists the other two ways out. |
Merge train and merge queue rejections
Added in 2.3
Each row names the repair that ran when the merge train or queue dropped the merge request. Kraft never re-queues a merge request on its own.
| The reason says | What happened | Fix |
|---|---|---|
dropped from the merge train in node <node>: <reason>; ...; Kraft never re-queues a merge request on its own (or merge queue) | Someone took the merge request off, the forge gave a reason Kraft can't read, or the node declares no on_merge_rejected. No escalation agent runs. | If you removed it on purpose, decide what comes next. Otherwise queue it again on the forge, or run kraft item retry ID. |
the merge-rejection repair in node <node> committed nothing: <reason> (or committed nothing in <checkout> for a workspace member) | The repair changed nothing, so queueing again would only be rejected again. A commit in another checkout holds the item at the restart node. | Read kraft view logs ID, then run kraft item retry ID --steer "..." naming the fix. The repair runs again, and its commit goes through final_review. |
the merge-rejection repair in node <node> could not fix it: <reason>, or needs_context: <question> after a drop | The repair failed, or asked a question the repo couldn't answer, such as when the fix belongs in a repository that already merged. | Run kraft item retry ID --steer "<answer>". If the repair had committed, the item is held at the restart node and the retry goes through final_review again. |
resume: the merge-rejection repair in node <node> did not finish: <reason> | Kraft restarted mid-repair, or mid-restart after one. If a repair had started or the branch moved, the item is held at the restart node with its gates reopened. | Read kraft view logs ID, then run kraft item retry ID. On the merge node the retry finishes the restart or repairs again, never queueing the rejected head. |
<node>.on_merge_rejected exhausted after N restart(s) from '<node>' | Each repair and restart was rejected again until the rewinds ran out. The stop kind is cap. | Read the drops with kraft view events ID --type merge_queue_dropped, fix what keeps failing, then run kraft item retry ID; a retry resets the count. To allow more rewinds, raise that key under loops: in policy.yaml. |
Restarts and crashes
| The reason says | What happened | Fix |
|---|---|---|
... are executed by the running Kraft daemon ... | A task that runs inside Kraft itself failed. A rebase conflict doesn't stop here: see Worktree and git stops. | Run kraft admin update --restart, after pausing items that run in place. Or skip the node with kraft item skip ID. |
reattach: running session, PID identity unconfirmed, no result (pid N is not alive) | Kraft stopped with kraft admin stop --now, or stopped or restarted while an item that runs in place had an agent running. A clean stop ends only those; the steps of worktree items keep running. | Run kraft item retry ID. Before your next restart, pause in-place items: see A restart leaves local steps running. |
reattach crashed: <error> | Kraft started, found the item's agent session still running, and failed to take it over. The agent's sandbox, if it had one, was closed. | Run kraft item retry ID. If it happens again, open an issue with the error. |
executor crashed: ..., resume: ..., or a reattach ... reason other than the ones above | Kraft crashed while the item ran: it was killed, or the machine went down. A restart you asked for gives the reattach row above. | Run kraft item retry ID. If it happens again, run kraft admin doctor and open an issue. |
... but could not start a walk, with or without : <error> after it | A resume, retry, escalation retry, gate decision, the rate-limit poller or the wait scheduler put the item back to running, and failed before the executor took it over. | Run kraft item retry ID. After a gate decision the retry re-runs the node the item stood on: decide the gate again if it comes back. If it recurs, run kraft admin doctor and open an issue. |
skip could not start a walk for the node after the skipped one, or skip could not start a walk past the skipped scope | The skip is recorded, but the walk after it didn't start. | Run the same kraft item skip ID again, with the same --path for a task or step. A retry would re-run the node you skipped. |
Escalation turns and things that aren't a stop
Some stops reach you only after Kraft has tried an escalation turn on its own, up to three times (auto_escalate_stuck_cap in policy.yaml): a task that failed after its recovery, an exhausted fix loop and a stuck: stop. kraft view logs ID shows those turns. The other stops (a configuration or forge problem, a budget or time cap, a wait that ran out) come to you at once.
Three things look like a stop and aren't one, or need a different move:
- A pending gate waits for your decision:
kraft item approve IDorkraft item reject ID --note "...". - If the work is heading the wrong way rather than failing, pause it and resume it with a steer:
kraft item pause ID, thenkraft item resume ID --steer "...". - To move past a node without running it, run
kraft item skip ID.
Slices and their parent
Added in 2.6
A sliced item's slices are items of their own, each stopping for its own reason on these pages. kraft view list --status needs_human lists a parent with just the slices that match. The parent's stored status stays waiting, with a slices stop, and it isn't stopped for what a slice does, with one exception: when the slices run out of the budget they share with it, the parent stops too.
| What you see | What it means | Do this |
|---|---|---|
A parent under Needs you whose status is waiting | A slice needs you. | Open the slice from the parent's board row, which lists each slice that needs you, or by its own ID, and clear it as any stop. |
every slice was dropped, so a retry has nothing to join (a 409 on retry) | Each slice was abandoned or cancelled, so there is nothing to replay. | Run kraft item retry ID --path plan (or --restart) to slice the plan again, or kraft item abandon ID. |
... is refused while this item's slices are unjoined (a 409) | skip, complete, a retry from an earlier node and a draft acting at or behind the group wait for every slice to end. | End or drop each slice first, or abandon the parent. |
slice N (ID) conflicts with what is already joined ... on the parent, a conflict stop | Two slices changed the same lines, and the join's agent (resolve_join_conflict) couldn't replay slice N, or your library has no such task. The branch is back where the join stopped. | In cd "$(kraft repo path ID)", run the git cherry-pick -x ... the message names, resolve, then git cherry-pick --continue. Never git commit -m or --skip. Then run kraft item retry ID. |
the conflict handler left the parent where it cannot be put back ..., a checkout stop | The join's agent left a merge, rebase or other operation in the parent's worktree, so Kraft couldn't move the branch back. | In cd "$(kraft repo path ID)", clear that operation and run the git reset --hard <commit> the message names. Follow its replay steps, then run kraft item retry ID. |
A slice stopped on the parent's budget cap, and the parent with a budget stop | Its slices share the parent's dollar and token cap. The slice whose launch found it spent stops, the parent stops, and the other slices pause. | Run kraft item raise-budget PARENT --usd N. It raises the cap for the slices and retries those it stopped. The same on a slice (409) names its parent. |
Overview
Where to look when a work item stopped, the server won't start, a doctor row fails, or an add-on is refused.
Launch and setup stops
Fix a work item that stopped before its task ran, because Kraft refused the launch, couldn't make the worktree, or found a repo setting, registration or model it can't use.