Troubleshooting

Add-on validation messages

Find the message kraft admin addon validate printed for an add-on or collection you wrote, and the fix for each.

kraft admin addon validate PATH prints each problem as error: <file>: <message>, and exits 1. A line that starts with warning: doesn't fail it. <file> is an absolute path, shortened below. The first column is the text it prints. ... stands for text that varies. Messages that an install or update prints are on Add-on problems.

Manifests and layout

The message saysWhat happenedFix
<path>: holds neither .kraft/collection.json nor .kraft/addon.jsonPATH isn't a collection or an add-on directory.Point validate at the directory that holds .kraft/.
.kraft/addon.json: is not JSON: ...A manifest isn't 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 requiredaddon.json has no requires.Add "requires": { "kraft": "2" }.
.kraft/addon.json: 'version': String should match pattern ...version isn't 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 namespacekraft 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 nothingThe 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.1requires.kraft names a Kraft this one isn't. 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 ignoredKraft reads only lowercase names in the fixed layout.Rename the file, for example chains/ship.yaml.

What the files may hold

The message saysWhat happenedFix
library.yaml: tasks.implementer: harness 'codex' is not listed in requires.harnesses (['claude'])A task names a harness the manifest doesn't list.Add the harness to requires.harnesses, or use a listed one.
addons/release: requires harness 'ghosty', which harnesses.yaml does not defineChecked 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 underAn add-on can't 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-containedA 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-notesThe 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.

Copyright © 2026