Troubleshooting

Failed tasks and fix loops

Fix a work item that stopped on a question, a failed task, an exhausted fix loop or gate, a closed merge request or a crash, and a parent that waits on its slices.

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 saysWhat happenedFix
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 errorThe 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 saysWhat happenedFix
<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.6A 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 mergingSomeone 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 saysWhat happenedFix
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 dropThe 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 saysWhat happenedFix
... 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 aboveKraft 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 itA 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 scopeThe 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 ID or kraft 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, then kraft 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 seeWhat it meansDo this
A parent under Needs you whose status is waitingA 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 stopTwo 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 stopThe 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 stopIts 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.
Copyright © 2026