# Troubleshooting

## CLI Failures

CLI failures include a human-readable message. Add `--json` where supported to receive structured fields suitable for automation.

CLI failures include a human-readable message. Add `--json` where supported to receive structured fields suitable for automation. Every HTTP error the server answers, an unknown route, a method the route does not serve and a malformed body, query string or path parameter included, uses a JSON body with `error`, `code`, `disposition` and optional details for conflicts, limits, Blob ranges, external sources, or recovery. A malformed request is `400`, a body without a JSON content type `415`. MCP tool calls report the same body beside the HTTP status ([MCP](/content/docs/operations/mcp#results-and-errors/index.html)).

Do not parse human-readable error text when a structured field is present.

### Server Discovery

Remote graph commands first make an anonymous `HEAD /healthz` request to the configured service root. Discovery sends neither the data bearer token nor URL Basic-auth credentials; reverse proxies must allow that public probe. A timeout or connection failure is reported with a credential-safe cause category and means the data request was not sent. HTTP discovery refusals retain their status.

### HTTP Errors

Each `code` is sent under the statuses `ErrorCode` in `openapi.json` names beside its meaning: one, except `branch_start_refusal`, which is `409`, or `410` for `not_retained`.

| Status | Meaning | Usual action |
| --- | --- | --- |
| 400 | Invalid request, query, schema, configuration, or external-Blob policy | Correct the request; retrying unchanged will fail again. |
| 401 | Missing or invalid bearer token. | Supply a token configured by the server. |
| 403 | The resolved actor is not authorized. | For `forbidden`, change policy or use an authorized identity. |
| 404 | Graph, query, branch, entity, or route is unavailable. | Check the name and applied cluster revision. |
| 405 | The path is served, but not with this method. | Use a method the `Allow` header lists. |
| 408 | The request body did not arrive before its deadline. | Send the request again; nothing was admitted. |
| 409 | Concurrent change, duplicate ID, merge conflict. | Inspect structured details; not every conflict is retryable. |
| 410 | Required change-feed history was reclaimed. | Capture and durably install a new baseline, then resume from its terminal cursor. |
| 412 | Blob entity-tag or graph-commit precondition failed. | Refresh the Blob ETag or retry with the correct header. |
| 413 | Request or operation exceeded a bounded resource limit. | Split or reduce the operation using the reported limit. |
| 415 | The body's content type is not one the route accepts. | Send JSON with `Content-Type: application/json`. |
| 416 | Blob byte range is outside the value. | Use the returned length to choose a valid range. |
| 424 | An allowed external Blob source could not be read. | Restore source availability or correct its URI/credentials. |
| 429 | Server or per-actor admission limit reached. | Use the whole-command disposition below before retrying; preserve `Retry-After`. |
| 500 | Server or stored-data integrity failure. | Check server logs; do not assume partial success. |
| 503 | Admission is closed, the server's OIDC identity snapshot has expired. | Inspect the structured error. |

### Failed Data-Write Commands

Every server error body, and every CLI data-write and read failure, carries a `disposition`: `effects` is `none`, `partial` or `unknown`, and `action` is `fix`, `refresh`, `retry`, `recover` or `reconcile`. The server decides it for the request it answered by the first row that matches:

| Error | `effects` | `action` |
| --- | --- | --- |
| Any error before the request submitted a write | `none` | the refusal's own. |
| A write whose completion the server could not settle | `unknown` | `reconcile`, or `recover`. |
| A refusal before the write started | `none`, or `partial` | the refusal's own. |
| Any other error after a write | `unknown` | `reconcile`, or `recover`. |

### Conflicts

A `409` is not one universal retry signal:

- A read-set or version conflict means another writer changed an input.
- A key conflict means strict insertion found an existing ID.
- A merge conflict requires an explicit resolution on one branch before merging again.
- A full-text incompatibility includes `full_text_index_rebuild_required: { "index": "…", "reason": "…" }` with `code: "conflict"`.

### Writer Epoch

A branch at storage format v17 carries a writer epoch, a number that starts at 0. A claim raises it by one and makes the claiming process the branch's owner; a claim by the process that already holds the epoch writes nothing.

### Storage-Format Mismatch

If a graph was written by a different storage-format generation, the binary refuses to open it and names the required release line.

### Cluster Failures

- Run `cluster validate` before `plan` or `apply`.
- Apply refuses existing unmanaged roots and missing managed graphs that remain declared.

### Maintenance Failures

If `optimize`, `index build`, `index rebuild`, `repair`, `cleanup` or `upgrade` cannot write or flush its output, the CLI returns a failure without repeating the operation.

### Useful Diagnostics

```bash
omnigraph version
omnigraph snapshot --target ./graph.omni --json
omnigraph commit list --target ./graph.omni --json
omnigraph cluster status --target ./company-brain --json
omnigraph repair --target ./graph.omni --json
```
