Launch and setup stops
Kraft checks a task's launch and its worktree before the agent starts, so these stops cost no tokens. The first column is the text the board and kraft view show ID print. ... stands for text that varies. A row either holds the whole fix or links to an entry below.
A task Kraft wouldn't 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 (kraft admin doctor often names it), then run kraft item retry ID. The rows below are the common causes. |
could not start ... with cannot run: forge ..., cannot run: forge_account ..., cannot run: forges.yaml does not load, gh is not installed ... or no forge is recorded for this repo | The launch needs a forge account or CLI that is missing or doesn't match. | See Forge stops. |
could not start ... with declares neither test_scopes nor test_command in repos.yaml | The repo has no test command, and Kraft won't guess one. | See declares neither test_scopes nor test_command. |
could not start ... with kraft: no just recipe `<recipe>` in this item's justfile (its base is <branch>) Added in 2.6 | A test scope runs just <recipe>, but the item's branch, cut from <branch>, has no such recipe. | Rebase the item onto a base that has the recipe, or change the test scope in repos.yaml, then run kraft item retry ID. |
... nothing registers it for Claude Code: ... | No kraft MCP server is registered, so Kraft refused a Claude worker. | Run kraft admin init. See nothing registers it for Claude Code. |
... is not on the PATH the worker gets, so Claude cannot start it: ... Added in 2.5 | Claude can't start the registered kraft MCP server, so Kraft refused a Claude worker. | Put kraft on PATH. See is not on the PATH the worker gets. |
could not start ... with stored model override is not a model id: clear it with ... | A model override on the item or a node isn't a model ID, such as sonnet 4. | Run the command the reason names. 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, couldn't be fetched again, or were edited. | See add-on ... could not be read. |
could not start ... with <repo-id>'s repo library is visible only to items in <repo-id> | The task's skill, agent profile or fallback is in another repository's repo library, which only that repository's items read. | Use a skill or profile of your own, an add-on's, or this repository's own library, then run kraft item retry ID. See Who can name it. |
could not start ... with repository '<id>' has no accepted repo library | The task names <id>:<name>, and <id> is a connected repository whose library isn't accepted. A repository's ID is never another tool's plugin. | Run kraft repo library to accept that library, or name the skill or profile another way. |
in-place items run unsandboxed; <setting> turns a sandbox on Added in 2.1 | The item runs in place, and its repo or a policy turned a sandbox on after it was filed. | Drop that sandbox, or file the item again with --worktree. See No sandbox, and no Cursor. |
cursor's permission hook writes .cursor/hooks.json into the folder it runs in; an in-place item cannot use it ... Added in 2.1 | The task's harness is Cursor, and its hook would be written into your checkout. | Pick another harness for the item, then run kraft item retry ID. |
<checkout>, the checkout this item runs in, is gone: put it back, or abandon the item Added in 2.1 | The in-place item's repo folder was moved or deleted. | Put the folder back where it was, then run kraft item retry ID, or kraft item abandon ID --reason "..." --yes. |
this item's one-off chain changed before it started and needs approval again: ... Added in 2.5 | The item's one-off chain changed after Kraft took it to start, so its custom content no longer matches what a person approved. | Select Start on the item, in the web UI or on a phone, then Approve and start in the review it opens. Approved through the API, it goes back to paused for a person to start. |
Setting up the worktree
| The reason says | What happened | Fix |
|---|---|---|
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 won't guess what to run in a fresh worktree. | Set setup_command on the repo, then Review & publish. See no setup_command declared. |
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 wouldn't make the item's worktree. | Run git config --global user.name "Your Name". See no user.name configured. |
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 run kraft item retry ID. |
declares neither test_scopes nor test_command
The item stops at its test node (verify on quick-task, verification on default) because Kraft won't guess a test command.
- Set
test_command(ortest_scopes) on the repo in Settings › Repos, then Review & publish, or set it inrepos.yaml. For a repo with no tests, set"".kraft repo connect PATHagain saves the command it now proposes. - Run
kraft item retry ID.
nothing registers it for Claude Code
No kraft MCP server is registered, so Kraft refused a Claude worker. The item stops at its first agent step with 0 tokens spent: spec on default, implementation on quick-task.
- Install the Kraft plugin and run
/kraft:onboard, or runkraft admin init. - Run
kraft item retry ID.
kraft admin doctor's mcp server row checks the same thing: see mcp server.
is not on the PATH the worker gets
Added in 2.5
Claude can't start the registered kraft MCP server, so Kraft refused the worker with 0 tokens spent, at the item's first agent step.
- Put
kraftonPATH, as inkraft: command not found. In a checkout of Kraft,just installinstalls the command. - Run
kraft item retry ID.
Still failing? The reason names each command and the file that registers it. A registered kraft entry fails when no command Claude could start it from is on the PATH a worker gets, or on the PATH the entry sets in its own env.
Your own Claude Code shows the same: claude mcp list or /mcp says the server failed to connect, with Executable not found in $PATH and a name: "kraft" for a server you registered, or "stdio" for the plugin's. It is usual when Kraft is installed only in a virtual environment, or runs as a service with a short PATH.
Two other ways out:
- Register the server by its absolute path. If
kraft admin initregistered it at user scope already, runclaude mcp remove --scope user kraftfirst, thenclaude mcp add --scope user kraft -- /path/to/kraft admin mcp. Claude takes a repo's local-scope or.mcp.jsonentry before that one, so fix a barekraftthere the same way. - Under a service, reinstall the service from a shell where
kraftruns, so it keeps thatPATH: seekraft on PATH.
kraft admin doctor's mcp server row fails on the same thing while the server runs, and only warns when no chain launches an unsandboxed Claude task. With no server it checks the shell's PATH instead, which may not be the server's, and only warns. It doesn't check a registration that only a repo has, in its .mcp.json or local scope.
stored model override is not a model id
A model override on the item or a node holds text that isn't a model ID, such as sonnet 4. The reason ends with the stored text. Before 2.0, an override could hold any text, so an old item can still carry one.
- Run the command the reason names,
kraft item set-overrides ID --clearorkraft item set-node-override ID --node N --clear, or set a valid model. - Run
kraft item retry ID.
no user.name configured
The same stop names user.email when that is the missing one. git has no commit identity for the repo, so Kraft wouldn't make the item's worktree: its commits would fail or carry an invented author.
- Set both for the user Kraft runs as, for every repo:
git config --global user.name "Your Name" git config --global user.email you@example.com
To set them for one repo, run the same commands without--globalinside it. - Run
kraft item retry ID.
no setup_command declared
The repo has no setup_command, and Kraft won't guess what to run in a fresh worktree. This is the usual first stop on a repo with no lockfile Kraft knows (see How connect proposes commands). The item stops at its first node.
- Set setup command on the repo in Settings › Repos (or
setup_commandinrepos.yaml). If the repo has nothing to install, turn No setup needed on there instead (""inrepos.yaml). - In Settings, select Review & publish: until you do, the change is a draft and the retry stops again.
- Run
kraft item retry ID.
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.
Caps, budgets and waits
Fix a work item that stopped on a dollar, token or time cap, and one that waits on CI, a review, a gate or a machine and nothing moves.