Troubleshooting

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.

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 saysWhat happenedFix
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 repoThe 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.yamlThe 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.6A 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.5Claude 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 libraryThe 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.1The 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.1The 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.1The 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.5The 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 saysWhat happenedFix
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.

  1. Set test_command (or test_scopes) on the repo in Settings › Repos, then Review & publish, or set it in repos.yaml. For a repo with no tests, set "". kraft repo connect PATH again saves the command it now proposes.
  2. 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.

  1. Install the Kraft plugin and run /kraft:onboard, or run kraft admin init.
  2. 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.

  1. Put kraft on PATH, as in kraft: command not found. In a checkout of Kraft, just install installs the command.
  2. 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 init registered it at user scope already, run claude mcp remove --scope user kraft first, then claude mcp add --scope user kraft -- /path/to/kraft admin mcp. Claude takes a repo's local-scope or .mcp.json entry before that one, so fix a bare kraft there the same way.
  • Under a service, reinstall the service from a shell where kraft runs, so it keeps that PATH: see kraft 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.

  1. Run the command the reason names, kraft item set-overrides ID --clear or kraft item set-node-override ID --node N --clear, or set a valid model.
  2. 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.

  1. 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 --global inside it.
  2. 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.

  1. Set setup command on the repo in Settings › Repos (or setup_command in repos.yaml). If the repo has nothing to install, turn No setup needed on there instead ("" in repos.yaml).
  2. In Settings, select Review & publish: until you do, the change is a draft and the retry stops again.
  3. Run kraft item retry ID.
Copyright © 2026