Troubleshooting

Start by confirming the binary and selected configuration:

olyx --version
olyx inspect
olyx check olyx.json
olyx doctor --config olyx.json

Errors are written to stderr. The process exits with status 2 for invalid CLI arguments and status 1 for runtime failures. See CLI reference for scripting behavior.

Run olyx doctor --probe to check whether the provider endpoint responds. Probes send no API keys or prompt content and do not validate keys or model access. After changing a provider key, restart the gateway: credentials load at startup. See doctor and diagnostics for details.

Configuration and credentials

Symptom	Resolution
Configuration file cannot be read	Check the current directory, OLYX_CONFIG, or pass --config FILE
Unknown configuration field	Remove unsupported fields; use the configuration reference
unknown_model	Use a name present under models in the selected configuration
Credential environment variable is absent	Export the variable named by the selected provider’s api_key_env in the shell running Olyx
Provider authentication fails	Confirm the key, account access, and endpoint; authentication errors do not trigger fallback
messages_required	Supply a nonempty messages array
output_token_limit_exceeded	Lower the request limit or raise policy.max_output_tokens
input_too_large	Reduce request size or adjust policy.max_body_bytes within its supported range

Check does not test keys or model access. Dry-run previews requests without provider execution; it does not prove that the provider will accept the request.

Preview a request before sending it, then capture its result separately from errors:

olyx route --input request.json --dry-run
olyx route --input request.json > result.json 2> error.log

Routing and replay

Connection failures, HTTP 429, and provider 5xx responses can trigger an ordered fallback if another provider is configured. Invalid requests and authentication failures stop the route. Inspect the failed trace to see attempted models and errors.

For trace_not_found, use the original database and check retention. For no_replayable_steps, select a trace containing a successful model step.

If a comparison fails, inspect the replay trace identified by the error. Earlier successful runs remain in local storage. Replay uses live provider calls.

olyx debug TRACE_ID --config olyx.json
olyx replay TRACE_ID --config olyx.json --model fast

Replay sends a new provider request. Resolve the original failure before retrying.

Storage and streams

A relative database path is resolved beside the configuration file. The directory must be writable. :memory: starts a new database on each invocation and cannot support replay across commands.

SQLite uses WAL files and waits up to five seconds for database locks. Let another writer complete rather than deleting journal files. See storage and backups before moving a database.

For request_interrupted, the process that owned the trace ended before the request finished. Recovery preserves saved attempts and does not resend the request. Inspect its trace before retrying; upstream usage may have occurred.

A stream without a completed event is incomplete. Inspect the error and trace, then explicitly run a new request if appropriate; the CLI will not switch providers after partial output.

If a trace seems to be missing, check that all commands use the same configuration:

olyx inspect --config /path/to/olyx.json
olyx doctor --config /path/to/olyx.json
olyx debug --config /path/to/olyx.json

Report a reproducible issue

Include the CLI version, operating system and CPU architecture, command syntax, exit status, and a minimal redacted configuration/request. Include whether the request used streaming, compatible HTTP, or an installed plugin. Remove credentials and private prompt/response content before sharing logs or database files.

Open an issue in the CLI repository.

Diagnosing a Provider Plugin

First run olyx check on its configuration. A valid configuration does not prove that the executable exists or that its runtime handshake succeeds. Olyx does not launch a plugin during configuration checking or doctor --probe.

Error	Check
plugin_start_failed	Absolute executable path, permissions, interpreter, and installed libraries
plugin_capability_unsupported	Requested operation against both configured and advertised capabilities
plugin_version_mismatch	The first stdout event is hello with numeric protocol_version: 1
plugin_invalid_event	Every stdout line is a valid protocol event, with no log output mixed in
plugin_timeout	Adapter completion and plugin.timeout_ms; the deadline covers the whole invocation
plugin_result_incomplete	Final chat choices contain finish reasons
plugin_stream_result_mismatch	The last cumulative snapshot matches the final result, including usage
plugin_exit_failed	Child exit status; reproduce the adapter’s fixture mode independently

Olyx discards plugin stderr and returns error codes rather than raw provider messages. Reproduce the adapter outside Olyx when investigating its own implementation, and keep credentials out of shared logs. Run the conformance kit against the adapter’s fixture mode before testing a live service. Only unavailable and rate_limited errors allow plugin fallback, and only before a chat snapshot has been emitted.