> ## Documentation Index
> Fetch the complete documentation index at: https://docs.the40thieves.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Catalog

> Every canonical error code reliquary-tc can return, generated from the shared error factory so it cannot drift from the running server.

The complete error vocabulary, generated from the `err` factory map in
`@the-40-thieves/reliquary-tc-shared` so it never drifts from the running server. See the
[API Reference](https://docs.the40thieves.dev/reliquary-tc/tools/api-reference.md) for the response envelope these codes travel in, and the
[Tool Catalog](https://docs.the40thieves.dev/reliquary-tc/tools/tool-catalog.md) for the surface that raises them.

Errors arrive in the standard MCP error shape. The `code` below is what appears in the structured
payload; it is stable across releases and is what a client should branch on. Messages are defaults
and may be replaced at the throw site with something more specific about the failure.

> [!NOTE]
>
> This table is generated from the error factory (`bun run docgen:render`). Do not hand-edit the
> region between the markers — add the error to the shared `err` map and regenerate.

Every failure reliquary-tc returns carries one of these **39** canonical codes, **39** of which ship a recovery hint. The code is the stable contract — branch on it rather than on the message, which is a human-readable default that may be replaced with something more specific at the throw site.

| Code | Default message | Recovery |
| - | - | - |
| `aborted` | operation aborted by caller | The caller's AbortSignal fired before the operation finished. Re-issue the call fresh if the work is still wanted; this is not a transient failure of the operation itself. |
| `acl_denied` | path denied by folder ACL | This path is outside the folder ACL for this caller. Call inspect\_acl to see which roots are permitted and retry within one of them. |
| `bases_syntax_error` | invalid .base YAML or filter syntax | The .base file's YAML or filter syntax is invalid. Fix the file — read\_base shows how the server parses it. |
| `command_not_allowlisted` | command is not in the vault allowlist | The command is not in this vault's allowlist. Add it there (deny-by-default is intentional) — list\_commands shows what is currently permitted. |
| `compute_budget_exceeded` | operation exceeded its compute budget | The input exhausted its compute budget and will do so again identically — do not retry. Simplify the pattern or expression, or narrow what it runs over. |
| `concurrent_modification` | note changed since it was read | The note changed after you read it. Re-read it, re-apply your edit to the new content, and retry with the fresh CAS token — do not retry the stale one. |
| `conflict` | conflict | Re-read the current state, re-apply the change on top of it, and retry. |
| `content_rejected` | content rejected by poison scan | The content tripped the poison scan (risk: high) and was not written. Revise it to remove instruction-override, persistence-directive, hidden-text, or exfiltration-like phrasing, or write it with provenance: "authored" if a human is vouching for it. |
| `convention_blocked` | write blocked by a folder convention | Blocked by a folder convention marked block in SCHEMA.md; nothing was written. details.violations lists each rule. Fix the content (get\_conventions(path) shows the rules) and resend. Fixing a note that already broke the rules is never blocked. |
| `dql_error` | Dataview DQL error | Dataview rejected the query. Check it with validate\_dql, which reports the syntax error without running it. |
| `elicit_invalid` | elicit token invalid or expired | The token was rejected or expired. Re-issue the original call with no token to trigger a fresh confirmation prompt. |
| `elicit_required` | human confirmation required | A human must approve this call. A client with MCP elicitation gets a prompt; if it cannot answer it (unsupported, or auto-cancelled) mint one with `reliquary-tc elicit --hash <args_hash> --tool <name>` and resend. Never reuse an old token. |
| `embedding_provider_error` | embedding provider failed | The embedding backend failed. Retryable; if it persists, confirm the provider is reachable and the configured model is present (server\_health reports the provider). |
| `execute_command_disabled` | command execution is disabled for this vault | Command execution is off for this vault. It must be enabled in configuration; this is a policy decision, not a transient failure. |
| `forbidden` | scope or ACL denied | Missing a required scope (details.required lists it). Re-authenticate with a credential that grants it, or call inspect\_acl to see what this caller may reach. |
| `internal` | internal error | Unexpected server-side failure. Retryable once; if it persists, check server\_health and the server log rather than retrying further. |
| `internal_error` | internal error | Unexpected failure inside the handler. Retryable once; if it persists, capture the call and check the server log. |
| `invalid_input` | invalid input | Check the argument types and required fields against describe\_capability's inputSchema before retrying. |
| `jsonlogic_error` | JSONLogic expression invalid | The JSONLogic expression is malformed. Verify the operator names and that every operator's argument arity matches. |
| `not_found` | not found | Confirm the target exists before retrying — note\_exists checks one path, list\_notes enumerates, and search\_vault finds by content when the exact path is unknown. |
| `note_exists` | note already exists | Something is already at that path. Choose a different path, or use the tool's overwrite/append option if it has one. |
| `note_not_found` | note not found | Confirm the path first: note\_exists checks it, list\_notes enumerates the folder, search\_vault finds the note by content. |
| `operation_timeout` | operation timed out | The operation exceeded its time budget. Retryable, but narrow it first — a smaller limit or a more selective query is more likely to finish. |
| `overflow` | response exceeds byte budget | The response exceeded the byte budget. Narrow the request — a smaller limit, fewer paths, or a compact/paginated read — rather than retrying unchanged. |
| `path_ambiguous` | path resolves to multiple notes | More than one note matches. Pass the full vault-relative path — list\_notes or search\_vault will show the candidates to choose between. |
| `path_invalid` | path is invalid | Paths are vault-relative, must stay inside the vault, and must not traverse upward. Rewrite the path rather than retrying it. |
| `plugin_incompatible` | companion plugin API version is incompatible with this server | The companion plugin's API major does not match this server's. Permanent until one side is upgraded; retrying will not help. |
| `plugin_missing` | required Obsidian plugin not detected | The required Obsidian plugin is not installed or not enabled. Enable it in Obsidian, then run refresh\_plugin\_capabilities so the server re-probes. |
| `plugin_unreachable` | plugin detected but REST endpoint failed | The plugin is present but its endpoint failed. Retryable; check Obsidian is running and the Local REST API is enabled and reachable. |
| `read_only` | server is in read-only mode | The server is in read-only mode, so no write will succeed until that changes. Use a read tool, or take this up with whoever runs the server. |
| `read_only_mode` | vault is in read-only mode | This vault is configured read-only. Target a writable vault, or change the vault's configuration; retrying cannot help. |
| `replay_drift` | confirmation is stale: the target changed after it was requested | The target changed after this confirmation was requested, so nothing was applied and the old token is spent. Re-read the target, then re-issue the original call with no token to request a fresh confirmation; never resubmit the old one. |
| `requires_live_obsidian` | this operation requires a live Obsidian (Local REST API) connection | This capability needs a live Obsidian connection and the vault is headless. Start Obsidian with the Local REST API, or use a filesystem-only equivalent. |
| `secret_detected` | secret-shaped content refused | details.pattern\_ids and details.fields name what matched, never the value. Remove the secret-shaped text from those fields and retry, or set memoryDefense.mode to "redact" to scrub silently instead of refusing. |
| `throttled` | rate limit exceeded | Rate limit for this scope class. Back off before retrying, and reduce batch size or spread the calls; a tight retry loop will keep hitting it. |
| `unauthorized` | authentication required | Authenticate first: send a credential this server accepts, then re-issue the call. |
| `unsupported_base_filter` | base uses the Obsidian Bases expression DSL, which query\_base does not evaluate | This base uses Obsidian's Bases expression DSL, which query\_base does not evaluate. Read the base and filter the rows yourself, or simplify the base's filter. |
| `validation_error` | input validation failed | Read the tool's inputSchema via describe\_capability and correct the arguments; details names the offending field where one could be identified. |
| `vault_not_found` | vault not found | Use one of the ids from list\_vaults, or register the vault first with add\_vault (no restart needed). |

## Reading the Recovery column

Recovery hints say *what to do instead*; the `retryable` flag on the error says *whether* to retry.
They are deliberately separate — a code can be non-retryable and still have a clear next step.

A hint is a fixed string chosen by `code` alone. No path, query, caller, vault or argument is in
scope where it is selected, so a hint cannot leak vault content by construction rather than by
review. An em dash means the taxonomy declares no hint for that code — a considered choice, made
because guidance that only restates the message is noise, not an omission.

Where a failure can name specifics, those arrive in the error's `details` object (for example
`details.required` on `forbidden`, or the offending field on `validation_error`). Read `details` in
preference to parsing message text.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.