Troubleshooting

Diagnose and resolve common issues with ClawRouter.

Version 1.0.18

Activation Issues

Problem: "not_activated" (HTTP 403) on proxy requests

Cause: Your ClawRouter installation has not been activated yet. Solution:

  1. Open the dashboard at http://localhost:3030.
  2. Copy your Installation ID from the Awaiting Activation screen.
  3. Send it to support@clawrouter.qzz.io or Reddit u/Malek262.
  4. Once the developer confirms activation, click Check Activation.

Problem: Was activated but now shows "Awaiting Activation"

Possible causes:

  • You moved ClawRouter to a different machine (the Installation ID is machine-specific).
  • Local data was reset. Solution: Contact the developer. If on a new machine, send the new Installation ID.

Problem: "Check Activation" button doesn't work

Cause: Network issue preventing ClawRouter from reaching the activation server. Solution: Check your internet connection. If you're behind a firewall, ensure outbound HTTPS requests are allowed.

Proxy Request Errors

Problem: HTTP 401 "Invalid or missing API key"

Cause: Your client did not send a valid proxy API key -- the key is missing, wrong, or was regenerated (regenerating invalidates the old key immediately). Solution:

  1. Open the dashboard > Settings > Proxy API Key card.
  2. Click Copy and update the key in your client configuration (sent as Authorization: Bearer <key> or x-api-key: <key>).
  3. Or use the "Prompt for AI" dialog on the provider page -- it embeds the current key automatically.
  4. If you intentionally want to allow any key value, check the Require proxy API key toggle on the same card (not recommended).

Note: This 401 comes from ClawRouter itself, before any upstream request. A 401/403 from the upstream provider is a different issue -- see below.

Problem: HTTP 502 "Bad Gateway"

Cause: ClawRouter could not reach the upstream provider. Possible fixes:

  1. Check the Upstream URL in the provider's Settings tab -- make sure it's correct.
  2. Test the upstream URL directly in your browser or with curl.
  3. Check your internet connection.
  4. The provider may be temporarily down -- check their status page.

Problem: HTTP 504 "Gateway Timeout"

Cause: The upstream provider took too long to respond. Possible fixes:

  1. Increase the Timeout setting in the provider's Settings tab (default: 120000ms / 2 minutes).
  2. For slow reasoning models, set to 300000ms (5 minutes) or higher.
  3. Enable Retry on Timeout to automatically try the next key.

Problem: HTTP 429 "Rate Limited"

Cause: Your API key hit the provider's rate limit. What ClawRouter does: Automatically rotates to the next key with a cooldown on the rate-limited key (default 60 seconds, configurable in Settings > Rate Limit Backoff). If all keys rate-limited:

  1. Add more API keys to spread the load.
  2. Consider switching to Round Robin rotation to distribute requests more evenly.
  3. Wait for the backoff period to expire -- keys automatically recover from cooldown.

Problem: HTTP 401/403 "Unauthorized"

Cause: The API key is invalid, expired, or revoked. What ClawRouter does: Permanently disables the key and tries the next one. Solution:

  1. Check the key's Error History for details.
  2. Verify the key is valid in the provider's developer console.
  3. If the key was disabled incorrectly, re-enable it from the API Keys tab.
  4. Add a new valid key if needed.

Exceptions: Not every 403 is an auth error. A 403 "requires a subscription" body (Ollama Cloud gated models) is a model error -- the key stays enabled. A 403 access_terminated_error (Kimi Coding quota windows) is quota exhaustion -- the key backs off until the window resets and is never disabled. And not every 429 is a rate limit: Z.AI puts a business code in error.code that decides the outcome (1113 = hard billing > key disabled; 1308-1321 = quota windows > backoff only). See the provider-specific sections below.

Problem: Key backed off for a long time but not disabled (Kimi Coding)

Cause: A Kimi Coding quota window (5-hour, weekly, or monthly) is full. Kimi returns HTTP 403 access_terminated_error, which ClawRouter classifies as quota exhaustion -- not an auth error. What ClawRouter does: Backs the key off until its own exhausted window's reset -- read from the key's saved quota snapshot, so a 5-hour exhaustion cools down until the 5-hour reset and a weekly exhaustion until the weekly reset (no shared blanket cooldown). The key is never disabled and recovers automatically. Solution: No action needed. Check the provider's Quota tab (Fetch Quota button) for live per-key, per-window remaining quota and reset countdowns -- usable keys are sorted first. Add more keys if you regularly exhaust windows.

Problem: "Monthly usage cycle exhausted" but the Quota tab shows 5-hour/weekly quota available

Cause: The key's monthly billing cycle is exhausted -- a separate limit from the 5-hour and weekly windows. What ClawRouter does: The key is not disabled. It is retried in ~10-day steps anchored to its last successful use until the monthly cycle renews. Solution: No action needed -- the key recovers when the billing cycle renews. Route around it by adding more keys or a fallback provider if this happens regularly.

Problem: Requests succeed but return wrong/empty responses

Possible causes:

  • Incorrect API format configured for the provider.
  • Model ID is wrong or outdated. Solution:
  1. Verify the API Format matches the provider (e.g., use google-generative-ai for Gemini, not openai-completions).
  2. Use Fetch Models to get the latest model IDs.

API Key Issues

Problem: Key marked as "Disabled" -- how to re-enable?

  1. Open the provider's API Keys tab.
  2. Find the disabled key.
  3. Click the enable/disable toggle to re-enable it.
  4. Check the Error History first to understand why it was disabled -- it may have genuine auth issues.

Problem: How do I check if a key actually works?

Use the built-in connection testing: click the test button on the key's row (or Test All Keys). Each test runs a free /models check followed by a 1-token generation probe. A 401/403 means the key is invalid; hard billing (HTTP 402, "insufficient balance" / insufficient_quota) means the account is out of money ("recharge required"); a window-quota body (Kimi access_terminated, Z.AI codes 1308-1321) means the key is valid and recovers at the window reset; other results confirm the credential is accepted. The latest result persists in the Last Test column.

Auto-disable: When a test proves a key definitively invalid (bad/expired key or hard billing), the key is auto-disabled -- you'll see a "Failed · disabled" badge and a warning toast naming the key. Transient failures, rate limits, window quota, and content-moderation rejections never disable a key.

Problem: "This provider uses no API keys" error when adding a key

Cause: The provider's API Key Mode is None (keyless presets like OpenCode Zen, Kilo AI (Free), Ollama Local). These providers need no keys -- ClawRouter sends the required headers automatically. Solution: Nothing to fix -- use the provider as-is. If you intended to use your own key (e.g., a Kilo AI account key), create the provider from the Kilo AI preset (Managed mode) instead of Kilo AI (Free).

Problem: Key shows "Unstable" status

Cause: The key has more than 3 consecutive errors but hasn't been disabled (errors are not auth-related). Solution: Check the Error History. The key may be experiencing temporary server issues. It will auto-recover when a request succeeds.

Problem: All keys in cooldown at the same time

Cause: All keys hit rate limits simultaneously. Solutions:

  1. Add more keys to the pool.
  2. Switch to Round Robin rotation to distribute load.
  3. Reduce request frequency from your client.
  4. Wait for the backoff period (default 60 seconds, configurable in Settings) -- cooldowns expire automatically.

Problem: Key stats seem wrong or inflated

Solution: Click the Reset Stats button on the key to zero all counters (total, success, failed, consecutive errors).

Model Errors

Problem: "Model not found" (HTTP 404)

Cause: The model ID is invalid or the model has been deprecated by the provider. Solutions:

  1. Go to the provider's Models tab > Fetch Models to get the current list.
  2. Update the model ID in your client configuration.
  3. Enable Model Fallback with alternative models as backups.

Problem: Model Fallback not triggering

Checklist:

  1. Is Model Fallback toggled to Enabled in the Models tab?
  2. Are there models saved in the fallback list? (Must have at least 2 models.)
  3. Is the error actually a model error? Check the log -- only MODEL_ERROR classification triggers fallback. Rate limits and auth errors do NOT trigger model fallback.

Problem: "PAID_MODEL_AUTH_REQUIRED" error

Cause: You're trying to use a paid model on a bypass provider (Kilo AI or OpenCode Zen) without a paid subscription. Solution: Use only Free models. Go to Models tab > Fetch Models and look for models with the Free badge.

Provider Fallback Issues

Problem: Fallback chain not triggering

Checklist:

  1. Is a Provider Fallback Chain configured? (Check the provider's Fallback tab.)
  2. Is the fallback provider enabled?
  3. Have all keys on the primary provider been exhausted? (Fallback only triggers after all keys fail, not on a single key error.)
  4. Is the circuit breaker OPEN? (If so, it should skip directly to the fallback chain.)

Problem: "No fallback providers" in notification

Cause: The primary provider failed but no fallback chain is configured. Solution: Go to the provider's Fallback tab (or the global Fallback page) > Add Fallback Provider.

Problem: Fallback provider dropdown is empty

Cause: No other providers exist yet (a provider cannot be its own fallback). Solution: Create another provider first, then add it as a fallback. Any provider can be a fallback target -- different API formats are translated automatically.

Problem: Fallback succeeds but with wrong model

Cause: The fallback provider uses different model naming conventions. Solution: Edit the fallback entry (click its model) and pin the exact model ID the fallback provider expects. Alternatively, leave it on Automatic and enable Model Fallback on the target provider so ClawRouter cascades through its saved model list.

Circuit Breaker Issues

Problem: Circuit breaker keeps tripping (OPEN)

Cause: The provider is consistently failing (default: 5+ failures in 60 seconds; threshold is configurable in Settings > Circuit Breaker Threshold). Solutions:

  1. Check the provider's status -- it may be genuinely down.
  2. Verify your API keys are valid.
  3. Check for rate limiting across all keys.
  4. Increase the circuit breaker threshold in Settings if the current value is too sensitive.
  5. Manually reset the circuit breaker from the provider's Settings tab after the issue resolves.

Problem: Requests going to fallback even though provider seems healthy

Cause: Circuit breaker might be OPEN from a recent failure burst. Solution:

  1. Check the circuit breaker status in the Settings tab.
  2. Click Reset to force it back to CLOSED.
  3. The next request will go to the primary provider.

Problem: Circuit breaker state lost after restart

Expected behavior: The circuit breaker is in-memory by design and resets to CLOSED on every restart. This ensures no stale state persists.

Connection & Network Issues

Problem: Dashboard not loading at localhost:3030

Possible causes:

  1. ClawRouter is not running -- run clawrouter status to check.
  2. Wrong port -- check if a custom port is configured.
  3. Firewall blocking local connections. Solutions:
  4. Run clawrouter start to start the server.
  5. Check clawrouter status for the actual port.
  6. Try accessing via http://127.0.0.1:3030 instead.

Problem: WebSocket "Reconnecting" status on Logs page

Cause: The WebSocket connection to the server dropped. Solution: Usually reconnects automatically within 3 seconds. If persistent:

  1. Check that ClawRouter is still running (clawrouter status).
  2. Refresh the page.
  3. Check for network issues between your browser and the server.

Problem: "EADDRINUSE" error on startup

Cause: Port 3030 (or your configured port) is already in use. Solutions:

  1. Run clawrouter stop first, then clawrouter start.
  2. Use a different port: clawrouter start --port 8080.
  3. Find and kill the process using the port: lsof -i :3030 (Linux/macOS).

Dashboard & UI Issues

Problem: Stats show "0" even though requests are being made

Possible causes:

  1. Stats use a 5-second cache -- wait a moment and refresh.
  2. Requests might be failing before reaching the logging stage. Solution: Check the Logs page for detailed request entries.

Problem: Notifications not appearing

Possible causes:

  1. WebSocket connection might be down -- check the connection indicator on the Logs page.
  2. The event type might not generate a notification (e.g., successful requests don't notify). Solution: Refresh the page to re-establish the WebSocket connection.

Problem: Provider list seems outdated

Solution: Navigate away from the Providers page and back. The data has a short stale time and will refresh.

CLI Issues

Problem: clawrouter: command not found

Cause: ClawRouter is not in your system PATH. Solutions:

  1. Run the install command again.
  2. Restart your terminal to reload PATH.
  3. Run directly from the installation directory: node /path/to/clawrouter/bin/clawrouter.js

Problem: clawrouter status says "not running" but dashboard works

Cause: ClawRouter might have been started in a different way (directly via npm start instead of the CLI service manager). Solution: Use clawrouter stop then clawrouter start to ensure it runs through the service manager.

Problem: clawrouter logs shows nothing

Cause: No requests have been made, or the service is writing logs elsewhere. Solution: Make a test request through the proxy and check again.

Provider-Specific Issues

OpenCode Zen -- HTTP 401 but key is correct

Explanation: OpenCode returns HTTP 401 for unsupported models with a "ModelError" in the body. ClawRouter correctly classifies this as MODEL_ERROR (not AUTH_ERROR), so your key won't be disabled. Solution: Check that the model ID exists. Use Fetch Models to get the current list.

Kilo AI -- HTTP 401 for certain models

Explanation: Kilo returns HTTP 401 with "PAID_MODEL_AUTH_REQUIRED" for models that require a paid subscription. ClawRouter classifies this as MODEL_ERROR. Solution: Use only Free models. Check the Free/Paid badges in Fetch Models. Note there are two Kilo presets: Kilo AI (Free) is keyless (free models only); Kilo AI takes an API key for the full catalog.

Anthropic-format providers (Anthropic, Kimi, MiniMax) -- missing anthropic-version errors

Explanation: Anthropic-format upstreams require the anthropic-version header. ClawRouter auto-fills anthropic-version: 2023-06-01 when your client doesn't send it, so this should not occur. Solution: If you see this error, check that your client isn't sending an empty anthropic-version header of its own.

Google Gemini -- HTTP 400 and key gets disabled

Explanation: Google returns HTTP 400 (not 401) for invalid API keys with "API_KEY_INVALID" in the body. ClawRouter correctly classifies this as AUTH_ERROR. Solution: Verify your API key at Google AI Studio.

Google Gemini -- Wrong Base URL format

Reminder: Google Gemini uses /v1beta in the proxy URL, not /v1. The correct Base URL format is:

text
http://localhost:3030/proxy/{provider-id}/v1beta

Anthropic -- HTTP 529 errors

Explanation: Anthropic uses a custom HTTP 529 status for overloaded servers. ClawRouter classifies this as OVERLOADED and retries the same key after 2 seconds (up to 2 times). Solution: If persistent, add more providers to your fallback chain or wait for Anthropic to recover.

Groq -- HTTP 498 errors

Explanation: Groq uses a custom HTTP 498 for flex tier capacity limits. ClawRouter classifies this as RATE_LIMIT. Solution: Wait for the rate limit backoff period (default 60 seconds, configurable in Settings), or add more keys / a fallback provider.

Z.AI -- Key disabled after a 429 "rate limit"

Explanation: Z.AI returns almost every error as HTTP 429 with a numeric-string business code in error.code. The code decides the outcome: 1113 (insufficient balance) is hard billing and disables the key; 1309/1314/1315 (expired/wrong plan) also disable it; 1308/1310/1316-1321 are self-resetting 5-hour/7-day quota windows (backoff only, never disabled); 1302/1313 are real rate limits; 1311 means your plan doesn't include the model (model fallback). Solution: Check the key's Error History for the actual business code. For 1113, recharge the account; for window codes, wait for the reset (visible on the Quota tab).

Z.AI GLM Coding -- Quota tab shows "key valid, no active plan"

Explanation: The key authenticates, but the account has no active GLM Coding Plan. Z.AI's monitor endpoint returns a "coding plan" error payload for such keys. The key is valid and is never disabled for this. Solution: Subscribe to a GLM Coding Plan on Z.AI, or use the key with the Z.AI API (general) preset instead, which is balance-based.

Z.AI -- Key auto-disabled from the Quota tab even though the API returned HTTP 200

Explanation: This is expected. Z.AI's monitor endpoint returns HTTP 200 with {"code":1000,"msg":"Authentication Failed","success":false} for a dead key. ClawRouter detects this envelope and treats it exactly like a real 401 -- the key is disabled, with the same error history and notification as a real failed request. Solution: Verify the key in your Z.AI console, replace it if revoked, or re-enable it from the API Keys tab if you believe it was a mistake.

MiniMax -- Requests succeed but errors in body

Explanation: MiniMax returns HTTP 200 for most errors with custom status codes in the response body. ClawRouter parses the body to detect these:

  • Status 1004, 2049, 1008 > AUTH_ERROR
  • Status 1002, 2045, 2056 > RATE_LIMIT Solution: Check the Error History for the actual error codes.

Ollama Cloud -- Key requirements

Note: Ollama Cloud uses header-based auth managed by ClawRouter. Add sk-not-required as the key. Do not leave the keys tab empty as the managed mode requires at least one key entry.

Ollama Cloud -- HTTP 403 "requires a subscription" on some models

Explanation: Ollama Cloud returns HTTP 403 "this model requires a subscription, upgrade for access" for plan-gated models. ClawRouter classifies this as MODEL_ERROR, not an auth error -- your key is not disabled. Ollama's API does not mark which models are free vs paid, so gated models are discovered at runtime: after repeated failures they show an amber "Skipped" badge on the Models tab (model circuit breaker). Solution: Remove the gated model from your fallback list (or upgrade your Ollama plan). With Model Fallback enabled, requests automatically cascade to the next working model.

Perplexity -- No models returned from Fetch

Explanation: Perplexity does not have a public /v1/models endpoint. ClawRouter returns a hardcoded list of known supported models instead. Solution: Use the models shown by Fetch Models, or check Perplexity's documentation for the latest model list.

Complete Reset

If all else fails and you need to start fresh:

  1. Stop ClawRouter:
    bash
    clawrouter stop
  2. Delete the local database file clawrouter.db (in the ClawRouter installation directory), then restart:
    bash
    clawrouter start
  3. You will need to reconfigure all providers and keys. Contact the developer if re-activation is needed.

Warning: This removes all providers, keys, and logs.