Skip to main content
kRouter

Troubleshooting

Real fixes for the problems people actually hit. OAuth refresh failures, rate-limit cascades, MITM certificate issues, dashboard freezes — all here.

If kRouter is misbehaving, start here. Every entry below is a real issue we've seen on user logs, with the actual fix.

"Verify your account" 403 on Antigravity

Symptom: The dashboard shows the Antigravity provider with a red badge that says "Verify your account". Every request to a Gemini model returns 403.

Cause: Google's anti-abuse system has correlated your OAuth token with a non-IDE client fingerprint and flagged the account.

Fix:

  1. Open the verification URL shown in the badge — sign in to the Google account from a fresh browser
  2. Wait 5-10 minutes for Google's backend to refresh
  3. In kRouter dashboard, click Test Connection on that provider
  4. If it goes green, you're back

If it stays red, the account is permanently flagged. Add a fresh account and let kRouter rotate to it via the combo you set up.

"TPM rate limited" but my daily quota is fine

Symptom: Dashboard shows lots of brief 429s but the daily quota tracker says you have 98% remaining.

Cause: Per-minute token throughput limit (TPM), not daily quota. kRouter classifies this correctly since v0.5.49 — the account is cooled for only 90 seconds, not the full 30 minutes.

Fix: Nothing to do — wait 90 seconds and the account comes back. Or set up a combo so requests fall through to the next provider while TPM cools.

If you keep hitting this, your IDE Autopilot is firing too many parallel requests. Reduce the concurrency in your IDE's settings.

OAuth token refresh fails on Claude Code

Symptom: Claude Code provider shows red "401 Unauthorized" and won't reconnect.

Cause: Refresh token has been revoked (Anthropic logged you out remotely), or the refresh endpoint changed in an upstream update.

Fix:

  1. Dashboard → Providers → Claude Code → Reconnect
  2. Complete the OAuth flow again in the browser tab that opens
  3. Test the connection

If the OAuth flow itself fails, your locally cached client credentials are stale. Update kRouter: npm install -g @sifxprime/krouter@latest.

MITM intercept not working on macOS

Symptom: You enabled MITM mode but Antigravity / Kiro IDE traffic doesn't appear in the request log.

Cause: The root CA wasn't installed in the system keychain, or /etc/hosts didn't get written.

Fix:

  1. Dashboard → Profile → MITM → click Reinstall certificate
  2. Approve the keychain prompt (you'll need your sudo password)
  3. Open Keychain Access → System → search "kRouter" — you should see the CA, marked Always Trust
  4. Restart your IDE (it caches the previous connection state)

On Apple Silicon Macs, also ensure your IDE is running natively (not under Rosetta). Some IDE versions cache certificates per-architecture.

MITM intercept not working on Windows

Symptom: Same as macOS but certutil failed during setup.

Fix:

  1. Quit kRouter and your IDE
  2. Right-click the kRouter tray icon → Run as administrator
  3. Dashboard → Profile → MITM → Reinstall certificate
  4. Restart your IDE

Windows requires elevation to write to the system root CA store.

Dashboard freezes on "Loading providers..."

Symptom: Provider page spins forever, never shows tiles.

Cause: SQLite is locked because another kRouter process is still running, or a previous version is still attached.

Fix:

# Kill any stale process
pkill -f krouter
# Verify nothing is on port 20128
lsof -i :20128 || ss -ltn | grep 20128
# Restart
krouter -t

Build error: "EACCES" on npm install

Symptom: Global install fails with permission errors on Linux/macOS.

Cause: npm's global directory is owned by root.

Fix: Use npm's recommended approach with nvm:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# Reload shell, install Node 22
nvm install 22 && nvm use 22
# Now install kRouter
npm install -g @sifxprime/krouter

This puts npm's global directory inside your home folder so no sudo is needed.

Docker container exits immediately

Symptom: docker run sifxprime/krouter:latest starts and immediately stops.

Cause: Missing DATA_DIR env var or unwritable volume mount.

Fix:

# Make sure the host directory exists and is writable
mkdir -p "$HOME/.krouter"
# Run with explicit DATA_DIR
docker run -d \
  --name krouter \
  -p 20128:20128 \
  -v "$HOME/.krouter:/app/data" \
  -e DATA_DIR=/app/data \
  -e PORT=20128 \
  -e HOSTNAME=0.0.0.0 \
  sifxprime/krouter:latest
 
# Check the logs
docker logs -f krouter

If the logs show JWT_SECRET undefined, set it explicitly via -e JWT_SECRET=....

OpenAI-compatible client can't connect to localhost

Symptom: Your IDE shows "connection refused" pointing at http://localhost:20128.

Cause: Either kRouter isn't running, or the IDE is in a sandbox that can't see localhost.

Fix:

  1. Check kRouter is up: curl http://localhost:20128/v1/models
  2. If that 200s, the IDE is the issue. Try 127.0.0.1 instead of localhost — some sandboxes resolve them differently
  3. For OpenClaw specifically, you must use 127.0.0.1 (IPv6 resolution bug upstream)

OAuth callback URL mismatch

Symptom: "Invalid redirect URI" during OAuth setup.

Cause: You changed the PORT env var but the OAuth provider only knows the original port.

Fix: Either revert to port 20128, or update the OAuth client config at the provider's developer console to allow the new port.

Where to go next

If your problem isn't here, open a GitHub issue with the dashboard's logs and the version (krouter --version).