Troubleshooting | Omnigraph
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).
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": "…" }withcode: "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 validatebeforeplanorapply. - 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
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