Troubleshooting

Why did my item stop?

Find the reason a work item stopped and needs you, the fix for each, and what to do when an item waits on CI or a review.

Start here when a work item appears under Needs you (needs_human in kraft view list), or when one waits and nothing moves. Find the text Kraft shows in the tables under Find your reason: each row has the fix, or links to an entry that has it. A pending gate and the two waits on CI or a review are not stops: Escalation turns and things that are not a stop and Waiting on CI or a review cover them.

Check the cause before you retry

A retry without the cause reruns the same failure. Read the reason first, with these three commands:

Command	What it shows
`kraft view show ID`	The node it stopped on, and the reason.
`kraft view events ID --type work_item_needs_human`	The stop, with every field.
`kraft view logs ID`	The log of the session that stopped it.

Where a fix says retry, run kraft item retry ID, and add --steer "..." to tell the agent what to do differently; a retry you run resets the node's attempt counters. In Claude Code, /kraft:triage reads all three and suggests the next step. The events catalogue lists every field of a stop.

Find your reason

The first column is the text Kraft shows, in the item's side panel, in kraft view show ID and in the board's stop card. ... stands for text that varies. A row either holds the whole fix, or links to an entry under Stop reasons in detail.

Questions, failed tasks and logins

The reason says	What happened	Fix
`needs_context: <question>`	The agent asked a question it could not answer from the repo.	Answer it: `kraft item resume ID --steer "<answer>"`.
`task failed in node <node>: ...`	An agent task or command failed.	Read `kraft view logs ID`, then retry with a steer that names the fix.
`task failed in node <node>: ...`, and the log shows an authentication or login error	The agent CLI is installed but not logged in.	Run the agent once in a terminal and log in (`claude` for the shipped chains), then `kraft item retry ID`. `kraft admin doctor` checks only that it is on `PATH`.
A forge task (opening, syncing or merging the merge request), or a git push or fetch, failed, and the log shows `HTTP 401`, `Bad credentials`, `Authentication failed`, `could not read Username`, `Permission denied (publickey)` or `gh auth login`	Kraft holds no forge token, and the forge refused what `gh`, `glab` or git sent.	See Forge authentication fails.
The log shows `Could not resolve host`, `Connection timed out` or `Connection refused` on a forge or git call. The stop's `facts.cause` is `forge_unreachable`.	The machine the server runs on could not reach the forge.	Check that machine's network, DNS and proxy settings, then `kraft item retry ID`.

A task Kraft would not launch

The reason says	What happened	Fix
`could not start <task> in node <node>: ...`	Kraft refused the launch, and the rest of the reason says why.	Fix the named cause, often with `kraft admin doctor`, then retry. The rows below are the common causes.
`could not start ...` with `cannot run: backend: auto, but no forge is recorded for this repo`	The repo had no GitHub or GitLab `origin` when you connected it.	See `no forge is recorded for this repo`.
`could not start ...` with `declares neither test_scopes nor test_command in repos.yaml`	The repo has no test command, and Kraft will not guess one.	See `declares neither test_scopes nor test_command`.
`could not start ...` with `stored model override is not a model id: clear it with ...`	A model override on the item or a node is not a model id, such as `sonnet 4`.	See `stored model override is not a model id`.
`could not start ...` with `add-on <id> <version> could not be read: ...`	The item pinned a version of a Kraft add-on whose files are gone from this machine, and Kraft could not fetch them again. The rest says why.	See `add-on ... could not be read`.
`... nothing registers it for Claude Code: ...`	No `kraft` MCP server is registered, so Kraft refused a Claude worker.	See `nothing registers it for Claude Code`.

Setting up the worktree

The reason says	What happened	Fix
`no user.name configured in <repo>; set it before Kraft can commit` (or `user.email`)	git has no commit identity for the repo, so Kraft would not make the item's worktree.	See `no user.name configured`.
`no setup_command declared for <repo> in repos.yaml, so <id>'s worktree cannot be prepared. Declare one ...`	The repo has no `setup_command`, and Kraft will not guess what to run in a fresh worktree.	See `no setup_command declared`.
`setup command failed for <id>: '<command>': <output>`	The repo's `setup_command` ran in the new worktree and exited non-zero, and the reason ends with its output.	In the worktree (`cd "$(kraft repo path ID)"`), run the command yourself. Fix it, or the repo's `setup_command`, then `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 (`kraft view events ID --type findings_measured`), then retry with a steer.
`<node>.on_base_changed exhausted after N restart(s) from '<node>'`	The base branch kept moving: each restart from the named node found it moved again, until the restarts ran out.	Retry once the base branch settles; a retry resets the count. To allow more restarts, raise that key under `loops:` in `policy.yaml`. The shipped chain restarts `merge_request_feedback` from `verification`.
`<gate> exhausted after N rejection(s)`	A gate was rejected as many times as its chain allows.	Retry with a 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 attempt is not justified (`judge`).	Kraft has already tried an escalation turn on its own. Send a message with `kraft item escalate ID --message "..."`, or retry with a steer.
`the merge request was closed on the forge without merging`	Someone or something other than Kraft closed the item's merge request without merging it.	The board offers Reopen !N, Open a new MR (only when the item had opened one) and Cancel item…. See MR closed externally (the stop's `stop.kind` is `mr_closed`).
`a repair in node <node> finished with concerns ...`	A repair ran, but its agent doubted the result.	Read the concerns in the reason, then retry with a steer, or `kraft item skip ID`.
`<scope> is read_only, but it changed the worktree: ...`	A read-only step edited files.	Look at the named files, then retry.

Git state of the worktree

The reason says	What happened	Fix
`the conflict in node <node> cannot be resolved ...`	Rebasing onto the base branch hit a conflict nobody resolved.	Resolve it in the worktree (`cd "$(kraft repo path ID)"`), commit, then retry.
`untracked <paths> would be overwritten by the base branch; move or delete it, then retry`, or `git would not start the rebase onto the base branch ...`	Kraft went to rebase the item onto its base branch, and git refused to start, so nothing was rebased.	See Git would not start the rebase.
`<worktree> has a <name> in progress: inspect it, then delete ...`	The worktree holds a rebase, merge, cherry-pick, revert, bisect or autostash, so Kraft would not rebase or commit over it.	See A git operation is in progress.
`<worktree> is not on <branch>; check it out by hand, then retry`	The worktree's HEAD names another branch, so Kraft would not commit, rebase or push from it.	`cd "$(kraft repo path ID)"`, check that nothing of yours is on the named branch, `git checkout <branch>`, then retry.
`origin/<branch> is at <sha>, which Kraft did not push and this worktree does not have ...`	Someone pushed commits to the item's merge request branch, and Kraft's push would have overwritten them.	`cd "$(kraft repo path ID)"`, `git pull --rebase origin <branch>` to bring them in, then retry.
`origin no longer has <branch>, which Kraft pushed ...`	The item's branch was deleted from origin, usually with its merge request merged or closed, and Kraft will not recreate it.	To publish the work anyway, run the two `git update-ref -d` commands the reason names in the item's worktree, then retry. Otherwise abandon the item.

Caps and budgets

The reason says	What happened	Fix
`budget cap reached: ... on this work item`	The item's own dollar cap refused the next launch.	Raise that cap and retry in one step: `kraft item raise-budget ID --usd N`, or Raise cap on the item. See Raise a cap on a stopped item.
`budget_usd reached ...`, `token budget reached ...`	A policy `budget_usd` or `token_budget` refused the next launch.	See A policy budget or token cap refused the launch.
`budget cap reached: ... today, across every work item`	The daily cap, which nothing on the item raises, refused the next launch.	Raise `budget.daily_usd` in `policy.yaml`, or wait for local midnight, then retry. `raise-budget` is refused, and the item's page offers Retry with no raise.
`budget_usd cannot be checked: N launch(es) in ... reported no cost, and unknown spend is never counted as free ...`	A launch ran on a harness that reports no cost, on a model Kraft cannot price, so it cannot show the scope is under its `budget_usd`.	See A budget cap cannot be checked.

Time caps and waits

The reason says	What happened	Fix
`<scope> hit its time cap of N minutes`	A time cap ran out.	Raise it for this item, then retry: `kraft item set-policy ID --policy time_cap_minutes=240`. See Raise a cap on a stopped item.
`<scope> hit its total time cap of N minutes`	A scope's wall-clock cap, which waits and gates count toward, ran out.	Raise it for this item, then retry: `kraft item set-policy ID --policy total_time_cap_minutes=N`. A node or task needs its path in the key, such as `merge_request_feedback.ci.await_ci.total_time_cap_minutes=N`.
`gate <gate> waited past its timeout of N minutes`	Nobody decided a gate in time.	Retry to reopen the gate, then decide it.
`<task> timed out waiting ...`	An external wait (CI, a review) ran out.	See Waiting on CI or a review. Retry once the outside is fixed.
`rate_limit retries exhausted after N attempt(s)`	The agent's provider kept refusing for a rate limit.	Wait for the limit to reset, then retry.
A CI or automated-review failure, with a suggested retry	CI failed for its own reasons, or a cancelled run has no successor.	Retry once CI has recovered.

The sandbox and Kits

These stops have their own page, Sandbox and Kit stops. Each row below links to the entry for its text.

The reason says	See
... this launch is sandboxed in <repo> with no `network:` policy ...	A sandbox with no network policy
`kraft: a process in the sandbox was killed by its memory limit (<size>)`, or `... under its <size> memory limit (the runtime did not confirm it was the limit)`	The memory-limit row
`the Kit <ref> cannot be used: ...`, or `the Kit <ref> has not been fetched here yet ...`	A Kit is refused
`work item <id> runs sandboxed, and its workspace members <paths> are not the checkouts Kraft made ...`	Sandboxed workspace members
`workspace member <path> of <worktree> has no checkout Kraft made ...`, and four more like it	A sandboxed launch would not mount a member
`... runs sandboxed, and no connected repository is known for <paths> ...`, or `member <path> of <id>: ...`	A member's repository cannot be checked out
`work item <id> runs sandboxed, and its worktree holds git repositories Kraft did not create: <paths>. ...`	A nested repository Kraft did not create

Restarts and crashes

The reason says	What happened	Fix
`... are executed by the running Kraft daemon ...`	A task that runs inside Kraft itself failed.	Update and restart Kraft with `kraft admin update --restart`, after pausing running items, or skip the node.
`reattach: running session, PID identity unconfirmed, no result (pid N is not alive)`	Kraft was stopped or restarted (`kraft admin stop`, `restart`, `update --restart`, or the service) while the item's agent ran, and a clean stop ends every running agent.	The board shows the item as failed. Retry. Pause running items before your next restart: see A restart ends running agents.
`reattach crashed: <error>`	Kraft started and found the item's agent session still running, and the code that takes a running session over failed with the error shown. The agent's sandbox, if it had one, was closed.	Retry. If it happens again, open an issue with the error.
`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 did not start.	Run the same `kraft item skip ID` again, with the same `--path` for a task or step. A retry would rerun the node you skipped.
`... 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. `facts.cause` is `stranded`.	Retry. After a gate decision the retry reruns 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 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, not this one.	Retry. If it happens again, run `kraft admin doctor` and open an issue.

Escalation turns and things that are not 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 are not one, or need a different move:

A pending gate is not a stop. It 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, use kraft item skip ID.

Waiting on CI or a review

Kraft keeps checking on both waits. One that outlasts its timeout stops the item with <task> timed out waiting.

`merge_request_feedback` waits on "no checks yet"

The pull request has no CI checks, so nothing will ever pass. Do one of these:

Add CI that runs on pull requests.
Set ci_checks: false on the repo's entry in repos.yaml, so both CI waits, before and after the merge, pass at once.
File the item on the quick-task chain.

A pull request that conflicts with its base branch does not wait here, although GitHub runs no checks on it. Kraft rebases the branch onto the base at once, and a conflict the rebase cannot resolve stops the item instead of the wait running out.

`external_approval` keeps waiting

A branch rule on the forge requires an approving review. Have someone else approve the pull request, or remove the rule. Kraft checks again on its own.

Doctor failures: a failing kraft admin doctor row, which often explains a stop.
Raise a cap on a stopped item: lifting a budget or time cap and retrying.
Sandbox and Kit stops: the no-network-policy, memory-limit, Kit, workspace-member and nested-repository stops of a sandboxed item.
Getting help: where to ask when no reason here fits.

Edit this pageorReport an issue

Overview

Where to look when a work item stopped, the server will not start, a doctor row fails, or an add-on is refused.

Stop reasons in detail

The stop reasons that need more than one table row, each with what it means and the numbered fix.