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:

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

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