Add-on validation messages
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 says | What happened | Fix |
|---|---|---|
<path>: holds neither .kraft/collection.json nor .kraft/addon.json | PATH 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 required | addon.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 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 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 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 doesn't 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 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-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.
Related
- 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. - Add-on problems: what the
kraft admin addonverbs print when they refuse.
Add-on problems
Fix a work item that stopped on an add-on it can't read, or the message a kraft admin addon command printed when it refused to add a collection, install, update or remove an add-on.
Overview
Look-up pages for the web UI, the CLI, the console, Kraft Lite, configuration files, chain nodes, permissions, harnesses, triggers, the HTTP API, MCP tools, environment variables and events.