Troubleshooting

Catalog works, generation fails

Catalogs can be public. Inspect the request receipt for the upstream status and exact model. Confirm the key belongs to the intended free-mode account, the model is available in that account and the endpoint is correct.

Inspect the exact model, not just the provider name. Gemini 3.5 Flash-Lite passed native generation while older Gemini 2.5 IDs returned 404. Restricted ZenMux access returned 403, and Mistral required account activation/capacity. A code change cannot grant upstream access.

Slow Claude or repeated retries

A short hello still sends client instructions, tool schemas and history. Groq can reject oversized TPM input, NVIDIA can wait 30 seconds, and a fast empty-chain 503 can trigger minutes of CLI retries. Read Choose a responsive chain and Save Claude setup once in Browse guides. The latest gateway forwards x-should-retry: false for an exhausted chain; restored capacity is evaluated on the next request.

No eligible provider or missing tools

Open Route Inspector. Check enabled state, key availability, circuit cooldown, reported reset and capability skips. Models with unknown tool support are excluded from coding requests. A working text chat does not establish working tool calls.

Client cannot connect

• Use the gateway key, not the upstream key.
• Chat Completions and Responses clients use a base URL ending in /v1. Claude Code uses the root gateway URL.
• Use the actual local port. The default examples use 3000; match your configured gateway port.
• For the verified Codex 0.166 profile, merge configuration into config.toml and launch codex -p conflux.
• For OpenCode, create the provider block and select the generated provider/model ID.
• Hosted clients cannot reach your laptop localhost. Use a reachable HTTPS gateway.

Missing forecast or savings

Forecasts require fresh, decreasing reported balances in the same reset window. Unknown quota is expected when a provider exposes no balance. Savings require a configured reference price and retained successful request usage.

Profile returns 429

Inspect the Harness Profile budget bar and its cumulative cap. Gateway rate limits can also return 429. Ordinary key quota rejection returns 402. Upstream errors are visible on individual receipt hops.