Skip to main content
kRouter

Troubleshooting

Fixes for common kRouter problems: banned or rate-limited accounts, OAuth sign-ins, MITM certificates, localhost and Cursor, Docker logins and the CLI.

Start with the version: krouter --version, or the image tag under Docker. Many problems below were fixed in a specific release, and the latest is always on npm.

Accounts and providers

"Verify your account" (403) on Antigravity or Gemini

Symptom: a connection shows as banned, its last error contains a Google verification link, and requests on that account fail with 403.

What kRouter does: it locks the whole account for 24 hours so it stops spending requests on it. If the same account is flagged again, the lock gets longer (up to 14 times as long), and after three times in a row the account shows a chronic ban badge.

Fix:

  1. Open the verification link from the connection's last error, and complete Google's check with that account.
  2. On the provider's page, press Test Connection One-by-One in the Connections section. A successful test clears the account's locks at once.
  3. If the account keeps getting flagged, disconnect it. A combo with another provider behind it keeps your tool working in the meantime.

More detail: the "verify your account" error page.

Many short 429s, but the quota tracker shows plenty left

Cause: a per-minute limit, not the daily or weekly quota. When a 429 arrives on an account whose quota data says it still has plenty, kRouter treats it as a per-minute limit and rests the account for 90 seconds instead of until the quota resets.

Fix: usually nothing; the account comes back on its own. With several accounts, round-robin spreads the load (Antigravity uses round-robin by default for this reason). If it keeps happening, your tool is sending many requests in parallel; lower its concurrency if it has a setting for it.

Every account of a provider is cooling down

When no account of a provider can take a request, kRouter returns an error with the earliest time one becomes available. A combo that ends in a different provider is the way to keep going. See the Zenith Routing Engine for how long each kind of cooldown lasts.

An OAuth connection stops working (401)

Cause: the provider revoked or expired the refresh token, for example after you signed out elsewhere or changed your password.

Fix: add the connection again and sign in with the same account. When the provider reports the account's email, kRouter matches on it and updates the existing connection instead of adding a second one. Then run Test Connection One-by-One. If the sign-in itself fails, update kRouter first; providers change their login flows from time to time.

An OpenCode Go model answers "400 ModelProtocolUnsupported"

OpenCode serves some models only on its Responses endpoint: the Grok, GPT Luna and Muse Spark models. Before v0.5.163, kRouter sent them to Chat Completions, and the error also cooled down your whole OpenCode Go account. Update kRouter. If OpenCode moves a model to another endpoint later, change that model's Protocol on the OpenCode Go provider page; see the Responses API section.

Connecting your tools

"Connection refused" on localhost:20128

  1. Check kRouter is running: curl http://127.0.0.1:20128/v1/models.
  2. If that works but your tool fails, use 127.0.0.1 instead of localhost in the tool. kRouter listens on IPv4, and a tool that resolves localhost to the IPv6 address ::1 finds nothing there. kRouter's own OpenClaw setup writes 127.0.0.1 for this reason.
  3. If you started kRouter with --port, use that port in the tool too.
  4. If the tool runs on another machine, kRouter must not be started with --host 127.0.0.1, and the tool needs an API key.

401 API key required for remote API access

The request did not come from the machine kRouter runs on, so it needs a kRouter API key: Authorization: Bearer <key> or x-api-key: <key>. Keys are on the dashboard's Endpoint page. Behind a reverse proxy, every request counts as remote.

Cursor cannot reach kRouter

Cursor sends requests from its own servers, so http://localhost:20128 never reaches your machine. Turn on the Tunnel on the Endpoint page and use its public URL, ending in /v1, as Cursor's base URL, with a kRouter API key. See Getting Started and why Cursor ignores a localhost base URL.

Codex does not go through kRouter

kRouter's Codex setup does not use OPENAI_BASE_URL. Check that ~/.codex/config.toml has model_provider = "krouter" and a [model_providers.krouter] block with wire_api = "responses", or apply it again from the dashboard's CLI Tools page; the full block is in Getting Started. If Codex reports a stream disconnect with a custom provider, see this write-up.

MITM mode

Traffic from Antigravity, Copilot, Kiro or Claude Desktop does not show up

Check these in order:

  1. The certificate. On the dashboard's MITM page, the MITM Root Certificate card should show it as trusted. If not, press Install Certificate (or Reinstall Certificate).
  2. The tool is turned on on the same page. Turning MITM on for a tool is what points its hostnames at 127.0.0.1.
  3. Restart the app after turning it on, so it opens new connections.
  4. Kiro IDE 1.0.228 or newer needs kRouter 0.5.137 or newer; earlier versions let its chat requests pass through untouched.

MITM does not work inside Docker, and Cursor is not supported by MITM at all.

macOS: the certificate goes into the System keychain and needs your password. In Keychain Access, search for 9Router MITM Root CA. If it is installed but not trusted, delete any older entry with that name and install again.

Windows: installing the certificate and editing the hosts file need administrator rights. Accept the administrator prompts when they appear, or start kRouter from a terminal opened as administrator so none are needed.

Linux: kRouter installs the certificate into the system store your distribution uses (Debian and Ubuntu, Fedora and RHEL, Arch, openSUSE) and needs your sudo password.

Dashboard and login

Docker: logging in with 123456 is refused

Symptom: the login page says the instance has no password yet and that the default only works from the machine running kRouter.

Cause: 123456 is public, so it only works from the machine kRouter runs on. Under Docker your browser reaches the container from outside it.

Fix: start the container with INITIAL_PASSWORD and log in with that:

docker rm -f krouter
KROUTER_PASSWORD="$(openssl rand -base64 18)" && echo "Dashboard password: $KROUTER_PASSWORD"
docker run -d -p 20128:20128 \
  -e INITIAL_PASSWORD="${KROUTER_PASSWORD:?run the line above first}" \
  -v "$HOME/.krouter:/app/data" --name krouter sifxprime/krouter:latest

Your data in ~/.krouter is kept. Then set your own password under Settings → Security. If ~/.krouter already has a password from an earlier install, that one applies instead.

Forgotten password

  • npm install: run krouter, choose Terminal UI, then Settings → Reset Password to Default. Then log in with INITIAL_PASSWORD if kRouter was started with one, otherwise with 123456 from the machine kRouter runs on.
  • Docker (image 0.5.162 or newer): docker exec krouter node scripts/reset-password.js.

The Docker container stops or will not start

Read the log first: docker logs krouter. The image already sets DATA_DIR, PORT and HOSTNAME, so you do not need to pass them. If port 20128 is taken on the host, map another one, for example -p 20129:20128.

If the log says Ignoring JWT_SECRET, the value you passed was too short or copied from documentation. Remove it; kRouter generates and saves its own.

The CLI

"kRouter needs Node.js 20.9 or newer"

kRouter refuses to start on older Node.js versions. Install a current Node.js release, then install kRouter again.

"Port 20128 is held by ... — not kRouter"

Another program is using the port, and kRouter will not stop a program that is not its own. Start kRouter on another port with krouter --port 20129, and point your tools at that port. A kRouter that is already running is stopped automatically when you start a new one.

EACCES on npm install -g

npm's global directory belongs to root. Do not use sudo; install Node.js with a version manager such as nvm, which keeps global packages in your home directory:

nvm install 22
npm install -g @sifxprime/krouter

"Unknown option"

The krouter command accepts only the flags in the CLI reference. Anything else exits with code 2 instead of starting on a default.

Still stuck?

Open an issue at github.com/sifxprime/krouter/issues with the output of krouter --version, what you ran, and the error. Server logs are printed with krouter -l, and the dashboard's Console Log page shows them live. For a security problem, report it privately instead; see Security.