---
title: "Errors"
description: "The lint issue kinds, error codes and runtime error strings the reference implementation emits, each with its cause and the fix."
canonical: https://harnesscontextprotocol.io/docs/reference/errors
---

# Errors

> The lint issue kinds, error codes and runtime error strings the reference implementation emits, each with its cause and the fix.

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](#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](/docs/concepts/skill#rules)
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](/docs/concepts/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](/docs/concepts/access#approvals)) |

### 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](/docs/community/roadmap#proposed-for-hcp12) proposes one for HCP/1.2.

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)