My agent won't connect

Almost every connection failure is one of three things: the wrong base URL, the wrong key, or a model id the client rejects. Work through the general checks first, then the per-client notes.

The base URL is wrong or missing /v1#

Symptom: Connection refused, 404, or "not found" errors from your client.

Cause: The base URL is missing /v1, or it points at a path that does not exist (such as a bare /chat).

Fix:

• OpenAI-compatible tools: use https://api.fluxrouter.ai/v1. The endpoints are /v1/chat/completions, /v1/responses, and /v1/models.
• Anthropic-compatible tools: use https://api.fluxrouter.ai/anthropic, with messages at /anthropic/v1/messages.
• There is no bare /chat path. If your config has one, that is the bug.
• If your client appends /v1 itself, set the base URL without it so you do not end up with /v1/v1.

The key is missing or wrong#

Symptom: 401 on every request.

Cause: A missing key, a typo, or a leftover OpenAI/Anthropic key.

Fix:

• Use your Flux key (starts with sk-) as Authorization: Bearer sk-.... The Anthropic path also accepts x-api-key: sk-....
• Remove any old provider key from the tool's config so it does not override your Flux key.
• See the Error reference for more on 401.

The model id is rejected#

Symptom: The client errors before sending, or the request returns a model error.

Cause: The model id is one the client does not allow, or one Flux does not recognise.

Fix:

• Set the model to flux-auto or a real flux-* id. See Models.
• Some clients keep a hard-coded model allowlist. If yours rejects flux-auto, pick a flux-* id the client accepts, or follow your agent's setup page under Connect your agent for a known-good config.

Claude Code gets a 404#

Symptom: Claude Code reaches Flux but every call returns 404.

Cause: Claude Code speaks the Anthropic protocol, so it needs the Anthropic base URL. Given the OpenAI base (which ends in /v1), it asks for /v1/v1/messages, which does not exist.

Fix: Set ANTHROPIC_BASE_URL to https://api.fluxrouter.ai/anthropic, with no /v1. The full recipe is on Flux for Claude Code.

Codex CLI connects but calls fail#

Symptom: Codex CLI returns errors even with the right base URL and key.

Cause: Codex must use the Responses API. If it is pointed at the chat-completions path, it will not work.

Fix: Configure Codex with wire_api = "responses" so it targets /v1/responses, and set the base URL to https://api.fluxrouter.ai/v1. See Flux for Codex.

Cursor only works in the chat panel#

Symptom: Cursor's chat works, but you expected it elsewhere in the editor.

Cause: Cursor with a custom base URL is chat-panel only. That is a Cursor limitation, not a Flux one.

Fix: Use Flux in Cursor's chat panel. Other Cursor surfaces that bypass the custom base URL will not route through Flux. See Flux for Cursor.

Copilot inline completions don't use Flux#

Symptom: You set Flux as a provider but inline completions are unaffected.

Cause: Copilot does not work with FluxRouter for inline completions.

Fix: Use the Copilot CLI path set out in GitHub Copilot, or pick another agent from Connect your agent for completion-style work.

Still not connecting?#

Confirm with a raw curl call, which removes the client from the equation:

curl -i https://api.fluxrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-auto","messages":[{"role":"user","content":"ping"}]}'

If curl works but your tool does not, the problem is in the tool's config (base URL, key, or model). If curl fails too, copy the X-Flux-Request-Id from the response and contact support. Full per-agent setup lives in Connect your agent.