Troubleshooting
Problems that come up when setting up and running Gavio, with what the message means and how to fix it. The messages below were reproduced with the Python SDK; the JavaScript and Java SDKs use the same variable names and settings.
Setup
ConfigurationError: No provider configured. Call .provider(...), .adapter(...), or .dev_mode(True).
The builder has no provider. Choose one:
Gateway.builder().dev_mode(True).build() # mock provider, no key
Gateway.builder().provider(Provider.OPENAI).model("gpt-4o-mini").build()ConfigurationError: ANTHROPIC_API_KEY not set (pass api_key= or set the env var)
The provider key is missing. Export the variable listed in the configuration reference (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, ...) in the process that runs your code, or pass it in code. In a container, a notebook or an IDE run configuration, check that the variable is set there too, not only in your shell.
AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT must be set
Azure needs both variables, and usually AZURE_OPENAI_DEPLOYMENT as well. The error appears on the first call, not when the gateway is built.
gavio: command not found
The gavio command comes with the Python package. Install it in the environment you are using (pip install gavio), or run it through that environment (python -m pip show gavio; with a virtual environment, activate it first). The npm and Maven packages have no command-line tool.
Everything shows a cost of 0.0
Dev mode uses the mock provider, which has no price. Costs appear once you use a real provider with a known model.
Inspector
The Inspector does not start
It is off by default. Use .inspect(True) on the builder or set GAVIO_INSPECT=1, then open http://127.0.0.1:7411 (or the port in GAVIO_INSPECT_PORT). See the configuration reference.
inspector mode 'full' captures raw prompt/response content. Outside dev mode you must opt in...
Full capture stores prompts and responses, so Gavio only allows it in dev mode unless you opt in. Use mode="redacted" or "metadata" (the default outside dev mode), or pass InspectorConfig(unsafe_content_capture_ack=True) if you accept the risk.
inspector bind '0.0.0.0' is not loopback; set an auth_token...
You cannot expose the Inspector beyond localhost without a token. In code set InspectorConfig(bind=..., auth_token=...). For gavio inspect pass --token:
gavio inspect --store audit.jsonl --bind 0.0.0.0 --token "$INSPECTOR_TOKEN"Without --token, gavio inspect prints this message and exits with 1. (Releases before this fix printed a Python traceback ending in the same ConfigurationError.) Requests to a token-protected Inspector need Authorization: Bearer <token> and get 401 otherwise.
gavio inspect: [Errno 2] No such file or directory
The --store file does not exist. Write one by adding AuditInterceptor(sink="jsonl://audit.jsonl") to your gateway and making at least one call. See the CLI reference.
Command-line tools
gavio cost report puts everything under unknown
Grouping by tenant, feature, user, endpoint, environment, workflow or tool needs those values in the records. Files written by the jsonl:// audit sink do not carry them, and the command prints a warning on stderr saying so. Group by agent_id, model, provider or session_id instead, or supply records with a cost_dimensions object. Details in the CLI reference.
gavio cost report: since must be an ISO 8601 timestamp ...
--since takes an ISO 8601 timestamp (--since 2026-10-01T00:00:00Z; no zone means UTC) or a duration such as 30m, 1h, 7d, 2w. The message since must be an ISO 8601 timestamp ... or a duration lists the accepted forms. (Releases before this fix rejected 1h and crashed with TypeError: can't compare offset-naive and offset-aware datetimes on a timestamp without a zone.)
gavio cost report: group_by must be one of [...]
The message lists the valid keys: agent_id, endpoint, environment, feature, middleware_chain, model, provider, session_id, tenant, tool, user, workflow.
gavio workflow release: [Errno 2] No such file or directory: 'trust.json'
The manifest points at files that must exist first. In the bundled example run python platform_workflow_release.py (it writes trust.json and profile.json) before gavio workflow release workflow.json.
gavio policy validate: unknown policy pack: <name>
Use a catalog name from gavio policy list (core, finance, healthcare, hr, legal, support, code-security, regional/eu, regional/india, regional/us) or a path to an existing pack file.
gavio eval run exits with 1 in CI
Exit code 1 means the gate failed (score below --fail-under, or a drop larger than --max-regression against --baseline) or an input file could not be read. The gate.reasons list in the JSON output, or the JUnit report, says which. Run with --summary --pretty to read it.
Still stuck?
Open an issue at github.com/manojmallick/gavio/issues with the SDK and version, the exact message, and a minimal script that reproduces it. Never paste API keys or raw prompts.