Troubleshooting
Where to look when a work item stopped, the server will not start, a doctor row fails, or an add-on is refused.
Find the message you are looking at in the first column, then follow its link.
Find your problem
| What you see | Go to |
|---|---|
A work item under Needs you, with a reason such as task failed in node ..., could not start ..., budget cap reached or stuck: ... | Why did my item stop? |
A sandbox, Kit, workspace-member or nested-repository reason, such as a process in the sandbox was killed by its memory limit or the Kit ... cannot be used | Sandbox and Kit stops |
no setup_command declared for ... on a first work item | no setup_command declared |
no user.name configured in ... | no user.name configured |
... nothing registers it for Claude Code: ... | nothing registers it for Claude Code |
could not start ... with declares neither test_scopes nor test_command in repos.yaml | declares neither test_scopes nor test_command |
task failed in node ..., and the log shows an authentication or login error | Questions, failed tasks and logins |
| A work item that waits on CI or a review and nothing moves | Waiting on CI or a review |
kraft: command not found | kraft: command not found |
kraft: refusing to start, or a port that is already in use | Kraft won't start: port already in use |
A webhook or proxy gets 403 unexpected Host | A webhook or proxy gets 403 "unexpected Host" |
A kraft admin doctor row that prints FAIL or warn | Doctor failures |
A kraft admin addon verb that refuses, such as no collection 'acme' under collections or namespace 'release' is taken, or an error from kraft admin addon validate | Add-on problems |
could not start ... with add-on <id> <version> could not be read: ... | add-on ... could not be read |
| A page that is not where you left it, or a theme that looks different, after an upgrade from 1.4 | Where the pages moved |
| A question about forges, harnesses, cost, platforms, specs, sharing chains with add-ons, Kraft Lite or the permission gate | FAQ |
| None of these matches | Getting help |
In this section
- Why did my item stop?: every other stop reason Kraft shows, with its fix, and the two waits that need no stop.
- Stop reasons in detail: the stop reasons that need more than one row, each with its numbered fix.
- Starting and reaching Kraft: a missing
kraftcommand, a taken port, and a rejectedHost. - Doctor failures: every row
kraft admin doctorcan print, and how to clear it. - Sandbox and Kit stops: the memory-limit, Kit, workspace-member and nested-repository stops of a sandboxed item.
- Add-on problems: what
kraft admin addonprints when it refuses a collection, install, update or removal, and whatvalidatereports in an add-on you wrote.