Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
131 lines (82 loc) · 4.9 KB

TROUBLESHOOTING.md

File metadata and controls

131 lines (82 loc) · 4.9 KB
Raw

Troubleshooting relay-ai

Common issues when launching Claude Code through relay-ai claude. For Claude Desktop gateway setup, see CLAUDE_DESKTOP_SETUP.md.

“Not logged in · Please run /login” after picking a model

What you see

Claude Code starts and shows the right model in the status bar (e.g. moonshotai/kimi-k2.6), but when you send a message you get:

Not logged in · Please run /login

Common cause: you chose No on the API key prompt

When Claude Code detects an ANTHROPIC_API_KEY in the session (relay-ai sets this for your chosen provider), it may ask:

Detected a custom API key in your environment
Do you want to use this API key?
  1. Yes
  2. No (recommended)

If you pick No, Claude Code remembers that choice and refuses to use the key. relay-ai is routing through your provider correctly — Claude Code is blocking the key you rejected.

This is not a relay-ai bug and does not mean your Nvidia/Groq/Zen provider is misconfigured.

Fix: approve the key in Claude Code’s config

Claude Code stores your answer in ~/.claude.json under customApiKeyResponses.

  1. Quit Claude Code if it’s still open.
  2. Open ~/.claude.json in a text editor.
  3. Find the key suffix shown in the prompt (last part of the masked key, e.g. iFYB03v8xy4E-xJEYpN8).
  4. Move that suffix from rejected to approved:
"customApiKeyResponses": {
  "approved": [
    "anything",
    "iFYB03v8xy4E-xJEYpN8"
  ],
  "rejected": []
}
  1. Save the file and run relay-ai claude again.

Easier next time: when the prompt appears, choose Yes. Claude Code usually remembers approved keys and won’t ask again for that key.

If you use Claude Max / Pro subscription elsewhere

You may also have a real Anthropic API key in your shell (~/.zshrc, etc.). That’s fine for other tools. relay-ai replaces ANTHROPIC_API_KEY in the Claude Code child process with your provider key (OpenCode, Nvidia, Groq, …). If the prompt confuses you, pick Yes when launching through relay-ai.

Provider works in relay-ai models but not in providers list

Zen and Go are cloud builtins: they appear when you have an OpenCode API key, even if they aren’t saved in ~/.relay-ai/providers.json. relay-ai providers list shows them with · cloud builtin. Imported BYOK providers (Anthropic, Nvidia, Groq, …) come from the registry file.

OpenCode import saved placeholder API keys

If you ran relay-ai providers import before v0.1.x and see refresh failures for Anthropic (anything) or Vertex (a), those came from OpenCode's config, not Claude Desktop.

Current behavior: import validates keys before Keychain save:

  • Placeholders like anything, a, ollama → not saved (models still imported)
  • Real keys → probed against the provider API before save
  • Vertex / Bedrock / Azure → key not saved (gcloud/AWS auth)

To clean up an old placeholder in Keychain: re-run import (choose Use imported for each provider) or remove the provider and import again:

relay-ai providers import

--trace for proxy / API errors

If a model fails mid-session (not the login prompt above):

relay-ai claude --trace

After exit, relay-ai prints errors from ~/.relay-ai/logs/claude-debug.log (secrets redacted in the summary). The proxy also logs to ~/.relay-ai/logs/proxy-debug.log when --trace is set.

Mixed Anthropic + Relay mode (--http-proxy): favorites missing from /model

What you see

Claude Code starts on your normal Anthropic login, but /model only shows Anthropic models — saved Relay favorites never appear.

What should happen (v0.7.2+)

In --http-proxy mode, Relay seeds Claude Code's gateway models cache and merges favorites into model discovery so they show in the normal /model picker next to Anthropic models.

Quick checks

  1. Confirm you launched with mixed mode (relay-ai claude --http-proxy or answered Yes to keep normal Claude models).
  2. Confirm favorites exist and are compatible: relay-ai models.
  3. If /model still looks stale from an older session, delete ~/.claude/cache/gateway-models.json and relaunch with relay-ai claude --http-proxy.
  4. If your shell already sets a non-local HTTP_PROXY / HTTPS_PROXY / ALL_PROXY, this mode exits on purpose (proxy chaining is not supported yet). Clear those for the session and retry.

Docker / Server + Admin UI

Container deploy, ports, LAN advertise IPs, secrets.json, and Compose troubleshooting live in DOCKER.md. Quick checks:

docker compose ps
docker compose logs -f ui

Still stuck?

  1. relay-ai providers list — confirm the provider is there and enabled.
  2. relay-ai claude --dry-run — preview provider, model, and endpoint without launching.
  3. Open a GitHub issue with the provider name, model id, and (redacted) error text.