Errors

Lint issues are structured objects from hcpx lint, and runtime errors are the error string of a result envelope with ok: false. Both stay stable within HCP/1.x, so hosts may match on them. Code that handles a failure should start from Error codes, which most failures carry.

Lint issues#

Each issue is { kind, key, message }.

`kind`	`key`	Cause	Fix
`missing_surface`	`surface.json`	No manifest	Add `surface.json`
`missing_harness`	`HARNESS.md`	No Skill file	Add `HARNESS.md`
`missing_policy`	`policy.json`	No Policy file	Add `policy.json`
`missing_verb`	`<verb_key>`	Manifest command without a Policy entry	Add the entry
`missing_verb`	`<pack_id>`	`policy.surface_id` ≠ `id`	Make them equal
`extra_verb`	`<verb_key>`	Policy entry with no manifest command	Remove it or declare the command
`missing_stimulus`	`<ref>`	Trigger without `stimuli` entry	Add the entry
`extra_stimulus`	`<ref>`	`stimuli` entry without a trigger	Remove or declare
`write_stimulus`	`<ref>`	Trigger whose Policy `operation` is not `read`	Set it to `read`; a trigger never writes
`invalid_meta`	`hcp`	`hcp` block fails schema	Read the Zod message
`invalid_meta`	`pack_id`	`hcp.pack_id` ≠ `id`	Make them equal
`invalid_meta`	`openapi`	`openapi` adapter without ref	Add `openapi.url` or `.path`
`invalid_meta`	`sense_only`	`sense_only` with no triggers	Declare a trigger
`binding`	`wrap`	`wrap` adapter without `wrap.bin`	Add `wrap.bin`
`binding`	`plane`	`control` plane with non-`mothership` Binding	Set `binding.mode: mothership`
`wrap`	`verbs`	Wrap pack with neither named commands nor `pass_through`	Declare commands
`skill`	`<verb_key>`	The Skill never names a command, or its hot-path table names one the manifest does not declare	Make the Skill and the manifest agree
`skill`	`path`	A host-absolute path in `HARNESS.md`	Use a relative path or `~/.hcp/…`
`skill`	`secret`	Something that looks like a credential in `HARNESS.md`	Remove it and rotate it
`skill`	`mcp`	The teaching part presents MCP as the install or invoke path	Teach the CLI; mention MCP under Anti-patterns only

The skill rules are the four-face lint that Skill describes. hcpx install fails with lint failed: <messages joined by "; "> when any issue exists.

Error codes#

Most failures from the runtime and the CLI carry a stable code, a readable error, a hint written for an agent and often next, the exact commands to run. Agents should branch on code, never on the message text.

`code`	Meaning	What an agent should do
`confirm_required`	The command asks: Policy `confirm`, access mode `manual`, or an ask rule, and nothing satisfied it. Nothing ran; `preview` holds the command, its arguments, and the rendered CLI line, and `approval` the card and the answers a host may offer	With approvals `agent`, re-run with `confirm=true` only if the user approved this exact action with these values, in their request or after seeing `preview`. With approvals `human`, ask the user to approve it (`approval_id`) and run the same command again. Otherwise show `preview` and wait
`missing_argument`	A required argument has no value	Supply it; the hint lists every argument
`unknown_argument`	An argument name the command does not take	Use the suggested name ("did you mean")
`unknown_command`	The pack has no such command	Pick from the listed commands
`missing_command`	`hcpx exec <pack>` without a command	The response includes the pack's commands
`missing_pack`	`hcpx exec` without a pack	Run `hcpx commands`
`unknown_pack`	No such pack is installed	Run a `next` command: the suggested pack, or `hcpx search`
`not_activated`	Installed but not activated	`hcpx activate <pack_id>`
`not_installed`	`hcpx activate` on a pack that is not installed	`hcpx install` first
`no_pack`	`hcpx install` on a path without `surface.json`	Point at the pack directory, or scaffold one
`denied`	The Principal lacks a grant	Stop and tell the user
`denied_by_rule`	The user's access rules forbid this command	Tell the user; do not reach the same result another way
`human_only`	An access command (`approve`, `reject`, `mode`, `allow`, `ask`, `deny`, `rules rm`) ran inside an agent	Show the user the command; they run it
`bad_approval`	`hcpx approve` or `reject` on an unknown, used, or expired id	See `hcpx approvals`; ask the agent to run the command again
`bad_mode` / `bad_pattern` / `project_cannot_allow`	Invalid access settings	Follow the hint
`usage`	A CLI command is missing a required argument	Follow the hint
`bad_argument` / `bad_args_json`	An argument is not `key=value`, or `--args` is not JSON	Fix the syntax as the hint shows
`no_project`	A pack with `wrap.workspace.mode: project` was called by a runtime that has no project directory	Run it through a local runtime started in the project
`bin_not_found`	`hcpx wrap` could not find the CLI on `PATH`	Install it, or pass its path
`wrap_failed`	`hcpx wrap` could not write the pack	Pick another `--id` or `--dir`

Runtime errors#

Lifecycle#

`error`	Cause
`unknown pack <id>`	`pack_id` not in the runtime's catalog
`pack <id> not activated`	Exec or connect before activate
`cannot activate unknown pack: <id>`	Activate an id not in the catalog (thrown)
`pack <id> is not installed`	CLI activate of an uninstalled pack (`not_installed`)
`pack <id> is installed but not activated`	CLI exec of an installed, inactive pack (`not_activated`)
`not activated: <id> — hcpx activate <id>`	CLI connect of an unactivated pack
`pack not installed: <id>`	Uninstall of an unknown pack (thrown)
`cannot uninstall bootstrap pack hcp-cli`	Uninstall of the bootstrap pack `hcp-cli`
`connect failed`	Driver connect returned `ok: false` without a message

Policy and confirm#

`error`	Cause
`no policy for <verb_key>`	Command lacks a Policy entry at exec time
`confirm required`	The command asks and nothing satisfied the ask (`confirm_required`; see Access)

Authorization#

Each message begins with denied: .

`error`	Cause
`denied: privacy.land brain requires project_id`	Land `brain` with no project scope
`denied: missing verb.exec.read for <pack>.<verb>`	No matching read grant
`denied: missing verb.exec.write for <pack>.<verb>`	No matching write grant
`denied: missing pack.connect`	Connect without grant
`denied: missing pack.install`	Install without grant
`denied: missing sense.enable`	Sense delivery without grant

Sandbox and adapter#

`error`	Cause
`sandbox: bin "<bin>" not allowlisted`	`wrap.bin` not in the allow-list (exit `127`)
`exit <n>`	Child exited non-zero with empty stderr
`<stderr>`	Child exited non-zero; stderr returned verbatim
`adapter <kind> not executable in reference runtime`	`openapi` or `sense_only` exec on the reference runtime

SDK construction (thrown)#

Message	Cause
`local runtime requires packDirs`	`Hcp.create()` with no `packDirs`
`proprietary-stub requires packs[]`	Stub runtime without loaded packs
`HarnessAgent ai-sdk runtime requires model`	`HarnessAgent` with the `ai-sdk` runtime and no `model`

Host intake#

`error`	Cause
`non-json cli output`	`execVerbViaCli` could not parse stdout; `raw` carries it
`no skill for <pack_id>`	`hcp__read_skill` for an unknown or unactivated pack

Availability reasons#

When a command's executable is false, its reason is not installed, not activated or missing <capability>.

Roadmap#

The code values above belong to the reference implementation. The specification has no registry of error codes yet, and the Roadmap proposes one for HCP/1.2.