> ## Documentation Index
> Fetch the complete documentation index at: https://theagenticguy.github.io/opencodehub/llms.txt
> Use this file to discover all available pages before exploring further.
> Scoped bundles: [user-guide](https://theagenticguy.github.io/opencodehub/_llms-txt/user-guide.txt) · [mcp](https://theagenticguy.github.io/opencodehub/_llms-txt/mcp.txt) · [contributing](https://theagenticguy.github.io/opencodehub/_llms-txt/contributing.txt)

# Error codes

Every MCP tool that fails gracefully (i.e. the tool ran but the
operation could not complete) returns a uniform envelope under
`structuredContent.error` with `isError: true`. Protocol-level
failures (unknown tool name, malformed JSON-RPC) raise the SDK's
`McpError` instead and are not enumerated here.

The canonical list lives at
[`packages/mcp/src/error-envelope.ts`](https://github.com/theagenticguy/opencodehub/blob/main/packages/mcp/src/error-envelope.ts).

## Codes

| Code | When it fires | Typical remediation |
|---|---|---|
| `STALENESS` | The index lags `HEAD` far enough to mistrust results. | `codehub analyze` (or `--force`). |
| `INVALID_INPUT` | A tool argument failed schema validation. | Correct the call; check required fields. |
| `NOT_FOUND` | The target symbol, repo, or group does not exist. | Confirm the name; run `codehub list` for repos. |
| `DB_ERROR` | The graph store returned an error during the query. | Check `codehub doctor`; inspect `.codehub/graph.lbug` (or `graph.duckdb` on the legacy backend). |
| `SCHEMA_MISMATCH` | The index was produced by a different CLI version with an incompatible schema. | `codehub analyze --force` to rebuild. |
| `RATE_LIMITED` | A downstream service (embedder, summariser) rate-limited the request. | Retry with backoff; reduce concurrency. |
| `INTERNAL` | Catch-all for unhandled exceptions reaching the tool boundary. | File an issue with the error `message`. |
| `NO_INDEX` | The repo has no `.codehub/` directory. | `codehub analyze <path>`. |
| `AMBIGUOUS_REPO` | More than one repo is indexed and neither `repo` nor `repo_uri` was supplied. | Retry with one of the `choices[].repo_uri` values. |
| `EMBEDDER_MISMATCH` | The store was indexed by a different embedder than the one currently configured. | Re-index with the configured embedder, or pass the documented force flag. |

## `AMBIGUOUS_REPO` envelope

`AMBIGUOUS_REPO` is the most common error a federated client encounters.
The structured envelope carries everything a caller needs to retry
deterministically.

```jsonc
{
  "isError": true,
  "content": [
    { "type": "text", "text": "Error (AMBIGUOUS_REPO): ...\nHint: ..." }
  ],
  "structuredContent": {
    "error": {
      "error_code": "AMBIGUOUS_REPO",
      "jsonrpc_code": -32602,
      "choices": [
        { "repo_uri": "github.com/org/api-svc", "default_branch": "main", "group": "platform" },
        { "repo_uri": "github.com/org/billing-svc", "default_branch": "main", "group": "platform" }
      ],
      "total_matches": 2,
      "hint": "Retry with repo_uri=<one of above>"
    }
  }
}
```

`choices[]` is capped at 10. When `total_matches > choices.length`,
the caller knows the list was truncated. Pick a `repo_uri` from the
list and retry the original call:

```jsonc
{ "tool": "context", "args": { "repo_uri": "github.com/org/api-svc", "symbol": "..." } }
```

`repo_uri` is the canonical first-class graph attribute promoted in
ADR 0012; every group tool emits it in the same form so its outputs
are valid `AMBIGUOUS_REPO` retry inputs.

## Generic envelope shape

For every other code, the envelope shape is:

```json title="error envelope"
{
  "isError": true,
  "content": [
    { "type": "text", "text": "Error (NO_INDEX): ...\nHint: ..." }
  ],
  "structuredContent": {
    "error": {
      "code": "NO_INDEX",
      "message": "Repo has no .codehub/ directory.",
      "hint": "Run `codehub analyze <path>`."
    }
  }
}
```

Clients should key on `structuredContent.error.code` (or
`error_code` in the `AMBIGUOUS_REPO` case) to decide whether to retry,
disambiguate, or abort.

## See also

* [CLI reference](/opencodehub/reference/cli/)
* [MCP overview](/opencodehub/mcp/overview/)
* [Troubleshooting](/opencodehub/guides/troubleshooting/)