Problem: Local model api_base_url misconfigured (Ollama etc.) —— Trove problem library

What you will run into

You point the gateway at a local model (e.g. Ollama) per the tutorial, fill in api_base_url, and every request fails: model not found, connection refused, or the gateway throws a routing error.

The tutorial makes "fill in the address" look trivial, but one wrong detail in how the address is written and nothing works.

Why this happens

The gateway (claude-code-router) does not request the model at the bare base address; it requests a full URL: base + /v1/chat/completions.

Filling only the base like http://localhost:11434 means the gateway can't build the full endpoint, so the server either 404s or refuses the connection;

missing the /v1 segment is the same - OpenAI-compatible endpoints usually live under /v1 (upstream Issue #239 scenario).

• The model name must match ollama list output character for character (including tags like :8b; case counts).
• The config change only takes effect after restarting the gateway - change without restart = looks unchanged.

The gateway talks to the model service via the standard OpenAI-compatible protocol: client -> gateway -> model service, and the last leg is a "POST to some URL on the model service".

That URL isn't arbitrary — the protocol fixes it: OpenAI-compatible endpoints live at {base}/v1/chat/completions, where base is the service address (including the port) and /v1/chat/completions is the protocol path.

The api_base_url in the gateway config is "base + path" fused into one field: filling only the base tells the gateway "the endpoint doesn't exist" (it can't build the protocol-required full path);

missing /v1 tells it "the endpoint lives at a nonexistent location".

That's the mechanism behind "one detail wrong and nothing works". The model name is a second exact match: the server indexes models by name, and a mismatch means model not found (tags and case count).

One more easily missed layer: config is loaded at startup, so without a restart the gateway's memory still holds the old config — "looks unchanged" is actually "not reloaded".

Step by step

1. Confirm the model actually exists — Required

ollama list

The output must contain the model name you want, e.g. qwen3:8b. If not, ollama pull <model-name> first.

2. Fill in the full URL — Required

Change api_base_url in the config to (Ollama example):

http://localhost:11434/v1/chat/completions

Key point: include the port and the full /v1/chat/completions path - not just the base.

3. Align the model name character for character — Required

The model name in the config must match ollama list output exactly (including the tag). If unsure, copy the first column of ollama list.

4. Restart the gateway and test — Required

ccr restart

After restarting, send a test request and confirm the error is gone.

How to confirm it works

Calling the full address directly with curl returns a normal response (measured usable form):

curl http://localhost:11434/v1/chat/completions -d '{"model":"<your-model-name>","messages":[{"role":"user","content":"hi"}]}' -H 'Content-Type: application/json'
-> HTTP 200 + JSON response (with choices)

Send the same request through the gateway: no more model not found / connection refused.

Other environments

Symptom

Requests fail after configuring a local model (Ollama etc.): model not found / connection refused / routing errors.

Cause

api_base_url must be the full URL (including the /v1/chat/completions path); writing only the base (e.g. http://localhost:11434) or missing /v1 fails (upstream Issue #239 scenario).

Solution

1. Write the full URL: http://localhost:11434/v1/chat/completions (Ollama example).
2. The model name must match ollama list output.
3. Save, restart the gateway, then test again.