olyx doctor and diagnostics

Check local setup

olyx doctor --config olyx.json
olyx doctor --probe --config olyx.json

doctor checks your configuration, whether the required API-key variables are set, and whether trace storage is accessible. It prints JSON and exits 1 if a check fails, or 0 if all checks pass. By default, doctor makes no network requests. It reads an existing database without changing it and creates then removes an empty test file in the nearest existing parent directory. It does not create trace tables or delete expired traces.

--probe additionally sends one unauthenticated HEAD request per distinct provider base URL, with a five-second timeout per endpoint and no redirects. Any HTTP response, including 401, 404, or 405, shows that the endpoint responded. It does not prove that your API key works or that a model can answer requests. The probe sends no API keys or prompt content.

A running gateway loads provider credentials at startup. After updating a key, restart the gateway. Running doctor in another shell checks that shell’s configuration and environment; it cannot inspect the keys loaded by another process.

Read structured errors

If a provider call fails, Olyx returns HTTP 502. An invalid application bearer token returns HTTP 401 instead. Provider connection and HTTP errors include an error.code, a trace_id, and details that help you investigate:

{
  "error": {
    "code": "provider_authentication_failed",
    "message": "The provider rejected the configured credentials or permissions.",
    "type": "server_error",
    "param": null,
    "trace_id": "trace_123",
    "provider": "api.openai.com",
    "alias": "fast",
    "upstream_status": 401,
    "retryable": false,
    "fallback": "stopped_non_retryable",
    "hint": "Check the configured provider credential and permissions. Running gateways load credentials at startup; restart after updating them."
  }
}

X-Olyx-Trace-Id also identifies traced error responses. Trace IDs are separate from error codes. Raw provider response bodies, credentials, and authorization headers are not copied into diagnostics. The provider field is the endpoint hostname.

Code	Meaning	Fallback
provider_authentication_failed	Upstream 401 or 403	Stops
provider_request_rejected	Other nonretryable upstream rejection	Stops
provider_rate_limited	Upstream 429	Tries remaining candidates
provider_unavailable	Upstream 5xx	Tries remaining candidates
provider_transport_failure	Connection, DNS, TLS, or transport failure	Tries remaining candidates
provider_credentials_unavailable	Configured credential absent at startup	Stops

A returned retryable provider error reports fallback: exhausted: configured candidates have already been attempted. retryable describes whether a later new request may be worth attempting, not an instruction to automatically retry. Never fall back after a successful upstream response has begun: partial streams may have delivered output or incurred usage. Stream failures use an SSE error event with a stable code and trace ID when available.

Inspect a failed trace

olyx debug TRACE_ID --config olyx.json

Debug prints a failure summary and hint to stderr before the full trace JSON on stdout. The JSON includes a top-level diagnostic for failed traces. Existing traces without structured metadata remain readable and direct you to their recorded provider attempts. Use the same configuration file as the original request to find its SQLite database. Debug does not require provider credentials.

/readyz checks local SQLite access; its response explicitly reports provider connectivity as not checked and credentials as not validated.

Plugin Checks

Doctor checks declared credential variables and local storage. --probe contacts compatible HTTP endpoints; it does not execute plugin commands or negotiate their capabilities. A passing doctor report does not certify an adapter. Use the plugin conformance kit to exercise its process and wire contract.