> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weaveos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Router troubleshooting

> Fixes for the errors and surprises customers hit most with Weave Router

When you report a routing problem, include the **session ID** (`/router-session` in Claude Code, or `/status`) and roughly when it happened. That is what lets Weave find the exact decisions behind it.

## Billing and access

<AccordionGroup>
  <Accordion icon="credit-card" title="API error 402: prepaid credits are depleted">
    Your organization's balance hit zero and the request presented no subscription credential that could cover the turn. An org admin can top up at [Organization settings → Weave Router](https://app.workweave.ai/organization/settings/weave-router). Turn on auto-recharge to avoid a repeat.
  </Accordion>

  <Accordion icon="triangle-alert" title="“Your Weave router credits are depleted, so this turn is running on your own Anthropic subscription”">
    Same cause, softer landing: the balance is empty, so the turn ran on your Claude or ChatGPT plan and paid-model fallback is switched off until credits are added. Routing quality is reduced in this state because the router can only choose plan-covered models. Codex shows the same warning with ChatGPT (Codex) in place of Anthropic.
  </Accordion>

  <Accordion icon="ban" title="An engineer hit a spend limit but their plan still has headroom">
    `You've reached your monthly Weave Router spend limit` means the engineer's monthly [spend limit](/router/billing#spend-limits) was reached. The org limit and per-key caps have their own messages: `Your organization has reached its monthly Weave Router spend limit` and `This router key has reached its spend cap`. Limits bound paid spend: after the org limit or a per-key cap, subscription-covered turns keep flowing unless subscription routing is **Use prepaid credits only**; after a per-engineer limit, they keep flowing only when subscription routing is set to **Strict pass-through until low**. Raise the limit, switch to that mode, or have them run `npx @weave-os/router off --claude` (then quit and reopen the client) to use their subscription directly in the meantime.
  </Accordion>

  <Accordion icon="wallet" title="The credit balance isn't going down">
    Turns served on your Claude or ChatGPT subscription don't consume credits — pass-through is working as intended. If you want to price the workload without the subscription, switch subscription routing to **Use prepaid credits only**.
  </Accordion>
</AccordionGroup>

## Routing behavior

<AccordionGroup>
  <Accordion icon="arrow-up-right" title="Everything routes to the most expensive model">
    Move the quality-versus-price dial toward price in **Models & routing → Routing priority** and save. If your team is on Claude subscriptions, the router deliberately favors Claude models — that quota is prepaid, so keeping work in-family is usually the cheapest option. If the mix still looks wrong after a change, send Weave a couple of session IDs.
  </Accordion>

  <Accordion icon="shield-x" title="A model we don't allow is being used">
    An org admin can uncheck it in **Models & routing → Models**, or uncheck the whole provider under **Providers**, then save. The router stops selecting it, including as a failover target for providers.
  </Accordion>

  <Accordion icon="circle-x" title="Upstream request failed, or the client doesn't recognize the routed model">
    This usually means a session was pinned to a model the client can't handle — most often after resuming a conversation that started before the router was installed. Clear it with `/unforce-model`, or start a fresh session. If it repeats, send the session ID to Weave.
  </Accordion>

  <Accordion icon="gauge" title="The context indicator is missing or differs from the client's usage">
    Claude Code's native percentage and the router's approximate request estimate measure different things. A served-model window can also differ by provider and from your client's local budget. Context is omitted when fields are invalid or unavailable, the router snapshot is older than five minutes, or an asynchronous fetch fails. Codex uses a terminal title and emits no status message in the conversation. Refresh happens on lifecycle events, so rerun the installer if your managed helper predates this support. Existing custom status lines and unrelated hooks are preserved.
  </Accordion>

  <Accordion icon="scroll" title="A resumed session hits a context-window limit">
    The router filters candidates using a conservative per-request estimate. If every model is excluded, it admits the widest eligible candidates so the provider can decide actual fit. A genuine overflow is returned in the client's native form so the harness can compact. In Claude Code, try `/compact`; you can also start a new session or use `/force-model <model-id>` to select a larger window.
  </Accordion>

  <Accordion icon="gauge" title="Strict pass-through is routing before the threshold">
    In **Strict pass-through until low**, Anthropic-model turns still forward your subscription token — so seeing a Claude model other than the one you picked is not the same as being billed per API call. If the *requested* model is being substituted below your threshold, capture a screenshot plus the session ID and send it to Weave.
  </Accordion>

  <Accordion icon="flame" title="Token usage spiked right after installing">
    Grab the session IDs and the time window and contact Weave. Unexpected cache misses have caused this before and are treated as a bug, not expected behavior.
  </Accordion>
</AccordionGroup>

## Install and client issues

<AccordionGroup>
  <Accordion icon="terminal" title="The Claude Code status line never appears">
    The status line script needs `jq` on PATH. Install it, then run `claude --debug` and check stderr for errors invoking `cc-statusline.sh`.
  </Accordion>

  <Accordion icon="power" title="Turning the router on or off had no effect">
    Claude Code reads its router setting at launch — fully quit and reopen it. Codex and opencode pick the change up on their next run. Cursor is toggled in **Settings → Models**, not by the installer.
  </Accordion>

  <Accordion icon="monitor" title="Claude Code Remote Control fails while using Weave Router" id="claude-code-remote-control">
    [Remote Control](https://code.claude.com/docs/en/remote-control) requires Claude Code to reach the Anthropic API directly. It is unavailable when `ANTHROPIC_BASE_URL` points to a host other than `api.anthropic.com`, including Weave Router. An eligible claude.ai subscription login does not remove this custom-endpoint restriction.

    Turn routing off for your install scope:

    ```bash theme={null}
    # User-scope install
    npx @weave-os/router off --claude

    # Project-scope install; run from the repository
    npx @weave-os/router off --claude --scope project
    ```

    Fully quit and reopen Claude Code after the toggle: it reads the configuration at launch. Requests then go directly to Anthropic and bypass Weave Router; they are not routed, measured, or governed by Weave Router. The toggle preserves your Router configuration. Weave Router does not proxy Remote Control or automatically switch routing for it.

    When finished with Remote Control, restore routing with the matching command:

    ```bash theme={null}
    # User-scope install
    npx @weave-os/router on --claude

    # Project-scope install; run from the repository
    npx @weave-os/router on --claude --scope project
    ```

    Fully quit and reopen Claude Code again to resume routing.

    If Remote Control still fails with routing off, follow [Anthropic's current requirements and troubleshooting](https://code.claude.com/docs/en/remote-control#troubleshooting). Remote Control requires an eligible Pro, Max, Team, or Enterprise subscription and claude.ai sign-in; API-key authentication is not supported. Team and Enterprise organizations also need an Owner to enable Remote Control. Organization policy, cloud-provider routing, and network access can cause independent failures.
  </Accordion>

  <Accordion icon="package-x" title="npx resolves the wrong package">
    On npm 6 and older, use `npx --package @weave-os/router -y -- weave-router --claude`, or upgrade with `npm i -g npm@latest`.
  </Accordion>

  <Accordion icon="shuffle" title="I installed the router but wanted the Claude Code plugin">
    They are different products. Remove the router with `npx --package @weave-os/router -y -- weave-router --uninstall --scope user`, then follow the [Claude Code plugin](/tutorials/weave-plugin-installation) install.
  </Accordion>

  <Accordion icon="key" title="Everything stopped working after a key rotation">
    Rotating or revoking a key invalidates the old token immediately. Re-run the installer on each machine with the new key.
  </Accordion>
</AccordionGroup>

## Reporting

<AccordionGroup>
  <Accordion icon="clock" title="Spend or savings numbers look stale">
    Data normally lands within about an hour. Beyond that, contact Weave with the time range you're missing.
  </Accordion>

  <Accordion icon="chart-line" title="Savings look wrong compared to another tool">
    Savings are measured against the model your agent requested, not against another vendor's pricing. See [how savings are calculated](/router/reporting#how-savings-are-calculated).
  </Accordion>
</AccordionGroup>

Still stuck? Email [support@workweave.ai](mailto:support@workweave.ai) or message your shared Slack channel with the session IDs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.