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

# Troubleshooting setup

> The failures people actually hit installing, signing in, and connecting — and the fix for each.

## Sign-in

<AccordionGroup>
  <Accordion title="OAuth callback timeout after five minutes, or the browser never opened">
    You're on a remote machine over SSH; the callback landed on your laptop's loopback. Forward the port and sign in inside that SSH session:

    ```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    ssh -L 19876:127.0.0.1:19876 user@remote-host
    kilo mcp auth merv        # or: opencode mcp auth merv
    ```

    Refresh needs no tunnel afterwards. If `ssh` can't bind 19876, another sign-in on the laptop holds the port. Other clients: forward *their* callback port. [Authentication](/docs/merv/clients/authentication)
  </Accordion>

  <Accordion title="project(action=&#x22;list&#x22;) returns nothing">
    The grant reached no projects. Create one at [rapidreview.io/merv](https://rapidreview.io/merv) or via `project(action="create")`, or ask a member to add you. Sign in again choosing **All my projects** if you want the grant to follow you into new projects.
  </Accordion>

  <Accordion title="The client asks for a key">
    Native clients don't need one — manifests are URL-only. Only if a client can't do MCP OAuth (no browser, CI, OpenHands headless): **Settings → MCP keys**, then `Authorization: Bearer …` / `MERV_MCP_KEY`. [When a project key is still required](/docs/merv/clients/authentication#project-keys)
  </Accordion>

  <Accordion title="403 credential_audience_forbidden">
    An OAuth access token was used somewhere other than `/mcp`. Tokens are audience-confined; use the UI's own sign-in for `/api/…`.
  </Accordion>
</AccordionGroup>

## Connection

<AccordionGroup>
  <Accordion title="HTTP 426">
    Below the version floor (`/api/meta` → `min_proxy_version`). Update the plugin — commands on each [client page](/docs/merv/clients/overview).
  </Accordion>

  <Accordion title="HTTP 401 on the first call">
    Normal — it starts OAuth discovery. If it repeats after sign-in, the token store is stale: sign in again with the client's MCP auth command.
  </Accordion>

  <Accordion title="HTTP 404 on a project route">
    Not a member of that project. Membership is the authorization boundary.
  </Accordion>

  <Accordion title="Cursor: tools missing or a tool-count warning">
    Cursor caps around 40 tools across all MCP servers; Merv exposes 41 by default. Turn Storage off for the project (−6 tools) or disable other servers. Dotted-name warnings are harmless.
  </Accordion>

  <Accordion title="Hermes: tool names look wrong">
    Hermes renames dotted tools (`mcp_merv_workflow_status_and_next`). Calls still work.
  </Accordion>
</AccordionGroup>

## Skills and reviews

<AccordionGroup>
  <Accordion title="The agent doesn't know the workflow">
    Skills didn't load. Plugin clients: reinstall or update. Kilo/OpenCode: new session or `/reload`. OpenHands/Replit: paste the skill text — nothing installs there.
  </Accordion>

  <Accordion title="A review never completes, or the capability expired">
    The reviewer must be a separate session; capabilities last one hour. Open the experiment in the UI — its reviews are on the detail page. Ask the agent to call `review.request` again (it reissues a capability); on clients without subagents, open a second session and paste the handoff prompt. [Reviewer handoff](/docs/merv/clients/reviewer-handoff)
  </Accordion>
</AccordionGroup>

## Sandboxes and auto-run

<AccordionGroup>
  <Accordion title="sandbox.request answered needs_selection">
    Several hardware options fit; the agent must pick one from the response and request again with its provider-shaped values.
  </Accordion>

  <Accordion title="A run shows unknown or lost">
    `unknown`: the machine died before receipts were read — retained evidence may still settle it, otherwise rerun. `lost`: receipts were read and no completion sentinel existed. [Sandboxes](/docs/merv/concepts/sandboxes)
  </Accordion>

  <Accordion title="The runner printed a code but the machine never appears">
    Enter it under **Auto-run → Pair a machine**. Codes expire; `merv-agent-runner pair` prints a fresh one.
  </Accordion>

  <Accordion title="Settings pending won't clear · a platform is not ready">
    The runner applies changes at an idle cycle. `~/.merv/bin/merv-client harness` shows, per platform, whether the executable resolves; fix with `merv-client agent <platform> --command <exe>`.
  </Accordion>
</AccordionGroup>

Self-hosting problems: [Operations](/docs/merv/self-host/operations). Still stuck? Open an issue on [rapidreview-io/Merv](https://github.com/rapidreview-io/Merv/issues) with the client, the command, and the response.