Sandbox and Kit stops
Start here when the reason a work item stopped names the sandbox, a Kit, a workspace member, or a nested git repository in the worktree. Every other stop reason is on Why did my item 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.
| The reason says | What happened | Fix |
|---|---|---|
this launch is sandboxed in <repo> with no `network:` policy, which leaves the worker's network unrestricted and gates not enforced; add a `network:` policy to the sandbox (<address>), or, if you accept that, set `unrestricted_network: true` on it | The sandbox has no network: policy and does not set unrestricted_network. | See 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 sandbox's memory limit killed the task. In the second form the runtime did not confirm it, but the container exited 137 under the limit and Kraft did not stop it. | Raise resources.memory in the sandbox policy, or make the task need less, then retry. See Out of memory. |
the Kit <ref> cannot be used: ..., or the Kit <ref> has not been fetched here yet ... | The item's sandbox is a Kit Kraft could not fetch, or will not run. | See A Kit is refused. |
work item <id> runs sandboxed, and its workspace members <paths> are not the checkouts Kraft made ... | A member of the item's worktree is not the checkout Kraft made from its connected repository. | See Sandboxed workspace members. |
workspace member <path> of <worktree> has no checkout Kraft made ..., and four more like it | A sandboxed launch would have mounted a member Kraft could not check, so it did not start. | See 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 is not connected, is missing, is not the top of a repository, or already has the item's branch. | See A member's repository cannot be checked out. |
work item <id> runs sandboxed, and its worktree holds git repositories Kraft did not create: <paths>. ... | The worktree of a sandboxed item holds a nested git repository, and Kraft runs no git there. | See A nested repository Kraft did not create. |
Stop reasons in detail
A sandbox with no network policy
Kraft refuses every launch into a sandbox that has neither network: nor unrestricted_network: true, whatever the harness. Without network:, Kraft sets up no channel and does not restrict the container's network, so nothing keeps the worker from reaching Kraft's API. The reason is, in full:
<task>: this launch is sandboxed in /home/you/code/my-service with no `network:` policy, which leaves the worker's network unrestricted and gates not enforced; add a `network:` policy to the sandbox (https://itsomidkarami.github.io/kraft/reference/configuration/sandbox/network-policy), or, if you accept that, set `unrestricted_network: true` on it
Either add a network: policy to the repository's sandbox: in repos.yaml, or set unrestricted_network: true there to accept an unrestricted network and gates that are not enforced. The two keys cannot be set together. Then kraft item retry ID. See Without a network policy.
Sandboxed workspace members
A member of the item's worktree is not the checkout Kraft made from its connected repository. A sandboxed worker may have swapped it, or the item started before Kraft checked members out this way. Kraft stops because host git there would read config the worker can write.
Abandon the item and file it again, which checks each member out afresh.
A sandboxed launch would not mount a member
A sandboxed launch would have mounted a member Kraft could not check against its connected repository, or reach without a symlink, so it did not start. The reason is one of:
workspace member <path> of <worktree> has no checkout Kraft made ...this sandboxed launch was not given the checkout of workspace members ...setup command for <id> cannot run: its sandbox was not given the checkout ...<path> is not a directory; the member under it is not mounted... cannot be made in the sandbox's ref store ...
Retry. If the member's checkout changed, the check before the next task names it. If it recurs, report it as a bug.
A member's repository cannot be checked out
A workspace member's repository must be connected, at the path repos.yaml gives, for Kraft to check it out. Each reason below names the member and the item.
| The reason says | What happened | Fix |
|---|---|---|
<id> runs sandboxed, and no connected repository is known for <paths> ... | A member's repository is not connected, so Kraft has nowhere safe to check it out from. | Connect it with kraft repo connect PATH, then retry. |
member <path> of <id>: the connected repository <path> for <path> is missing ... | The member's repository is no longer at the path repos.yaml gives. | Reconnect it (kraft repo connect PATH), or fix its path in repos.yaml, then retry. |
member <path> of <id>: the connected repository <path> for <path> is not the top of a git repository ... | The path repos.yaml gives is a directory inside some other repository, so git there would act on that one. | Fix the member's path in repos.yaml to the repository's own top directory, then retry. |
member <path> of <id>: <repo> already has a branch <branch> at <sha>, not at <sha> ... | The repository already has a branch with the item's name, somewhere other than the commit the root points at. Kraft will not check it out and replace what the root records. | Look at that branch in the member repository. Move it to the named commit or delete it, then retry. |
A nested repository Kraft did not create
The reason starts work item <id> runs sandboxed, and its worktree holds git repositories Kraft did not create: <paths>. A sandboxed worker writes the config of any git repository it makes in its worktree, and git reads that config when it commits or rebases, so Kraft runs no git there until you look. Kraft checks before the walk, before each task launches, and before any other step that refreshes the worktree.
The stop names an untracked nested repository, a gitlink whose directory is populated, and a gitlink the branch added or moved since the base. A submodule the repository already had, left unpopulated, does not stop anything. A workspace member reason that says "It also holds git repositories Kraft did not create" names these paths too.
In the worktree (cd "$(kraft repo path ID)"), remove the named repositories, or run git rm --cached on the gitlinks. Then kraft item retry ID, or abandon the item. When a nested repository stops the item lists what counts.
A Kit is refused
An item whose sandbox is a Kit reads the Kit before its worktree is made. If that fails, the item stops needing you, and the reason names the Kit and why. The same check runs again before each task; there a failure ends that task's launch as a configuration error, and nothing runs outside the sandbox. The rest of the reason says which:
| The reason goes on | Fix |
|---|---|
`manifest inspect <ref>` failed: ..., or under Podman `pull -q <ref>` failed: ... or `image inspect <ref>` failed: ... | The CLI could not read the Kit: a wrong reference, a missing registry login, or a registry it does not trust. Check it with docker manifest inspect <ref> as the user Kraft runs as. |
<ref> is not a Kit: no vnd.docker.sandbox.kit.descriptor annotation | The image was not built with the Kit frontend (# syntax=docker/sandbox-kit:3). |
requires <type>; Kraft does not enforce it, is a kind: mixin ..., has a capability group ... | The Kit needs something Kraft does not run. Mark the capability optional: true, or remove it, and rebuild. Docker's published Kits are refused this way: build one for Kraft. |
credential service '<service>' has no binding ... | Add <service>: <DAEMON_ENV_NAME> under credentials in sandbox.yaml, and set that variable in the server's environment. |
A dotted path and a message, such as capabilities.1.config.apiKey: ... | The descriptor does not decode: fix the Kit at that path. |
has not been fetched here yet | A review, gate review, escalation turn, or a read through the artifacts or diff API ran before any task fetched the Kit. Retry the item. |
Fix the Kit or the policy, then kraft item retry ID. A changed Kit is a new
digest: put it in kit: in repos.yaml and file the item again, since its
sandbox is fixed when it is filed.
Related
- Why did my item stop?: every other stop reason, with its fix.
- Kits: what a Kit is and how Kraft runs one.
- Doctor failures: a failing
kraft admin doctorrow, which often explains a stop.