Troubleshooting

Add-on problems

Find the message a kraft admin addon command printed when it refused to add a collection, install, update or remove an add-on, or when validate rejected an add-on you wrote, and the fix for each.

Start here when a kraft admin addon verb refuses, or validate reports a problem in a Kraft add-on you are writing. A refused verb leaves addons.yaml, the lock and the store as they were, so run it again once you have fixed the cause.

An add-ons or add-on updates row of kraft admin doctor is on Doctor failures. A work item that stopped with add-on ... could not be read is under Stop reasons in detail.

To confirm a fix, run the verb again, then kraft admin addon list. kraft admin doctor does not report a refused install or update: its add-ons row reports what is installed, and add-on updates only the last auto-update.

Adding, installing, updating and removing

The first column is the text the command prints after its prefix. ... stands for text that varies, and a path is shortened.

install and update print ADDON@COLLECTION: refused: ... when the add-on or your instance is the problem, and ADDON@COLLECTION: failed: ... when git, the lock or the store is.
Every other refusal starts with error:.

Adding a collection

The message says	What happened	Fix
`<address>: fatal: '/nonexistent/repo.git' does not appear to be a git repository` and `fatal: Could not read from remote repository.`	git could not reach the address.	Check the address, and that this machine can reach it.
`<address>: ...` and one of `Permission denied (publickey)`, `Authentication failed`, `could not read Username` or `terminal prompts disabled`	`collection add`, `install` and `update` run git in your shell, and Kraft runs it without prompting, so a password or passphrase prompt fails. GitHub answers a missing or private `owner/repo` over https this way too.	Load your key into your shell's SSH agent, or set a git credential helper, then run the verb again. For GitHub, check the name and your access.
`<address>: fatal: transport 'file' not allowed`	The address is a path that is not a directory, so Kraft tried it as a git address, and a path is not one.	Check the path. For a git repository on this machine, give `file:///abs/path`.
`<address>: ref 'nonexistent' does not exist: fatal: couldn't find remote ref nonexistent`	The ref names no branch, tag or commit. Kraft reports it as `refused`, not as a network failure.	After a failed `collection add` nothing was added: run it again with a ref that exists. For a collection added earlier, fix its `ref:` in `addons.yaml`, then run `kraft admin addon update`.
`<commit>: no regular file .kraft/collection.json`	A git collection has no `.kraft/collection.json` at the ref Kraft read, so it is not a collection.	Check the address and `--ref`. The author lays one out in Publish a collection.
`[Errno 2] No such file or directory: '<dir>/.kraft/collection.json'`	A directory collection has no `.kraft/collection.json`.	Check the path you gave, or add the file as in Publish a collection.
`collection acme is already added from <source>; remove it first to add it from another source`	`addons.yaml` already holds a collection of that name, from a different address or directory.	Add it from the source it has. To change source, uninstall its add-ons and run `kraft admin addon collection remove NAME` first.

Auto-update runs in the server, which as a service may lack your SSH agent or credential helper: see add-on ... could not be read.

Installing and updating

The message says	What happened	Fix
`addons.yaml: release@acme: no collection 'acme' under collections`	The add-on's collection is not added on this instance.	Run `kraft admin addon collection add SOURCE`, then install again.
`collection acme has no add-on nope`	The collection does not list an add-on of that name.	Compare the name with `kraft admin addon collection list`, and check the collection's `ref`.
`declined release@acme: no terminal to ask at; pass -y to accept`	`install` and `update` show a review and ask first. With no terminal, as in a script, they decline.	Read the review in a terminal, then pass `-y` in the script.
release@acme is already installed; `update` it, or pass --re-install to take the newest commit	`install` refuses an add-on the lock already holds.	Run `kraft admin addon update release@acme`, or `install release@acme --re-install` to take the commit the ref names now.
`requires agent profile 'ghost', which harnesses.yaml does not define`, or the same with `requires harness`	The add-on needs an agent profile or a harness this instance does not define.	Define it in `harnesses.yaml`, or ask the author to drop it from `requires`.
`1.0.0 needs Kraft 3.x; this is Kraft 2.4.1`	The add-on's `requires.kraft` names a Kraft this one is not. The message reads `needs Kraft 3.x` for a major, or `needs Kraft 2.9 or later` for a minimum.	Run a Kraft the add-on supports, or ask the author for a version that supports yours.
`addons.yaml: release@other: namespace 'release' is taken by release@acme; install one under another name with --as`	Two add-ons would share a namespace.	Install it again under another alias: `--as ALIAS`.
`its namespace 'release' is now a repository id`	An `id` in `repos.yaml` is the add-on's namespace. `validate` prints the same line after the path.	Install it with `--as ALIAS`, choosing an alias that no `id` in `repos.yaml` uses.
`a@acme: chains/go.yaml: ...: skill 'b:method' names this add-on's namespace 'b'; there are no add-on dependencies`	An installed add-on, `a@acme`, already names a skill in the namespace `b` of the add-on you are installing or updating, from before that add-on existed.	Install the add-on you are installing under another name with `--as ALIAS`, or ask the author of the installed add-on the message names to drop the reference.
`chain mine would stop resolving: ...: extends no task named 'release:implementer'`	The new version drops something one of your own files uses. `update --check` exits 2 for it.	Edit the chain the message names so it stops extending the removed task, or ask the author to keep it. The locked version keeps running.
`its chain release:ship does not resolve: ...: extends no task named 'release:implementor'`	The add-on's own chain names something the add-on does not declare.	Ask the author to correct the chain; `validate` finds it before publishing.
`is not in addons.yaml; install it first`	`update` named an add-on this instance has not installed.	Run `kraft admin addon install ADDON@COLLECTION`.
`release@acme: current: version 1.0.0 unchanged, but its files changed at <commit>; --re-install to take it`	Not a refusal: `update` exits 0. A new commit at the same version is not an update.	Ask the author to raise `version`, or run `kraft admin addon install ADDON@COLLECTION --re-install`.
`add-ons changed while you reviewed; run update again`	`addons.yaml` or `addons.lock` changed while the review was open. Nothing was written, and an install's new entry is not kept.	Run the same `install` or `update` again.

Removing

The message says	What happened	Fix
`cannot uninstall release@acme: its namespace 'release' is still referenced by` and a list of files	`uninstall` and `disable` refuse while your own files name the add-on's namespace.	Edit each file listed, or copy what you use into your library, then run the verb again.
`collection acme still has add-ons installed: release@acme; uninstall them first`	`collection remove` refuses while an add-on of that collection is installed or locked.	Run `kraft admin addon uninstall ADDON@COLLECTION` for each one listed, then remove the collection.

Any verb that writes

The message says	What happened	Fix
`another add-on change is running; try again`	Another `kraft admin addon` command, or an auto-update, held the add-on lock while this one waited 5 seconds.	Wait for it to finish, then run the verb again.
`a worker does not change the instance's add-ons`	A work item's agent ran a verb that changes add-ons. A worker may not.	Run the verb yourself, from a terminal.

Writing an add-on

kraft admin addon validate PATH prints each problem as error: <file>: <message>, and exits 1. A line that starts with warning: does not fail it. <file> is an absolute path, shortened below.

Manifests and layout

The message says	What happened	Fix
`<path>: holds neither .kraft/collection.json nor .kraft/addon.json`	`PATH` is not a collection or an add-on directory.	Point `validate` at the directory that holds `.kraft/`.
`.kraft/addon.json: is not JSON: ...`	A manifest is not valid JSON. The message gives the line and column.	Fix the syntax. JSON allows no trailing comma and no comment.
`.kraft/addon.json: 'requires': Field required`	`addon.json` has no `requires`.	Add `"requires": { "kraft": "2" }`.
`.kraft/addon.json: 'version': String should match pattern ...`	`version` is not `MAJOR.MINOR.PATCH`.	Write `1.0.0`, or `1.0.0-rc.1` for a pre-release.
`.kraft/addon.json: 'name': 'kraft' is Kraft's own namespace`	`kraft` is reserved for what Kraft ships.	Give the add-on another name.
`addons/release: .kraft/addon.json: name 'release' differs from its collection entry 'other'`	`addon.json` and the collection's `addons` entry name the add-on differently.	Make the two names the same.
`addons/release: add-on 'release' holds none of library.yaml, chains/, skills/ or profiles.yaml; it would add nothing`	The directory holds nothing but `addon.json`, or the entry's `source` points at the wrong one.	Add a file, or correct `source`.
`.kraft/addon.json: release 1.0.0 needs Kraft 3.x; this is Kraft 2.4.1`	`requires.kraft` names a Kraft this one is not. An install or update refuses it too, without the name.	Set `requires.kraft` to the Kraft you run, or upgrade Kraft. A source build skips the check.
`warning: .../chains/Ship.yaml is not part of the add-on layout and is ignored`	Kraft reads only lowercase names in the fixed layout.	Rename the file, for example `chains/ship.yaml`.

What the files may hold

The message says	What happened	Fix
`library.yaml: tasks.implementer: harness 'codex' is not listed in requires.harnesses (['claude'])`	A task names a harness the manifest does not list.	Add the harness to `requires.harnesses`, or use a listed one.
`addons/release: requires harness 'ghosty', which harnesses.yaml does not define`	Checked on a machine with a Kraft home: this instance lacks a harness or agent profile the manifest requires.	Define it in `harnesses.yaml`, or remove it from `requires`.
`library.yaml: tasks.lint: an add-on may not carry a subprocess task; a shell command runs outside the permission gate an agent works under`	An add-on cannot run commands.	Use an `agent` or `builtin` task. A command belongs in the repo's own configuration.
`library.yaml: tasks.implementer: policy.allowed_tools is not a limit; an add-on may set only budget_usd, deny_tools, ...`	An add-on's `policy:` takes limits only, never permissions.	Remove the key. The instance's `policy.yaml` sets permissions.
`chains/ship.yaml: ...: extends 'other:implementer' reaches outside the add-on; an add-on is self-contained`	A reference names another add-on.	Copy what you need into this add-on and extend that.
`addons/release: its chain release:ship does not resolve: ...: extends no task named 'release:implementor'`	A reference in the chain names nothing the add-on declares, often a typo. With no Kraft home, `validate` prints the lint message without `its chain ...:`.	Correct the name the message gives.
`...: selects skill 'release:release-notes', which resolves to no method: ...: add-on 'release' has no skill 'release-notes' at .../skills/release-notes/SKILL.md; a method Kraft ships is written kraft:release-notes`	The skill's directory or its `SKILL.md` is missing or misnamed.	Create `skills/release-notes/SKILL.md`. The directory name is the skill's name.

An add-on's files and What an add-on may set have the rules behind these.

Share chains with add-ons: write, validate, publish, install and update an add-on, step by step.
Add-ons and collections: every manifest field, addons.yaml, the lock, and when an add-on loads.
Doctor failures: the add-ons and add-on updates rows.

Edit this pageorReport an issue

Sandbox and Kit stops

Find the reason a sandboxed work item stopped, whether a sandbox with no network policy, the sandbox's memory limit, a Kit Kraft will not run, a workspace member Kraft cannot check out, or a nested git repository Kraft did not create, and the fix for each.

Overview

Look-up pages for the web UI, the CLI, configuration files, chain nodes, permissions, harnesses, triggers, the HTTP API, MCP tools, environment variables, and events.