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

# Troubleshooting

> Common failures and how to fix them fast.

## Install

<AccordionGroup>
  <Accordion title="No matching distribution found for glasswarp">
    Upgrade pip and retry: `python -m pip install -U pip glasswarp`.
    Package page: [pypi.org/project/glasswarp](https://pypi.org/project/glasswarp/).
    Inside the monorepo you can also use `python -m pip install -e sdk/python`.
  </Accordion>

  <Accordion title="ImportError for som_annotate / targets helpers">
    The grounding helpers need Pillow. Install the extra:
    `pip install "glasswarp[grounding]"`.
  </Accordion>
</AccordionGroup>

## Auth

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    `GLASSWARP_API_KEY` is missing, expired, or invalid. Create a fresh key in
    [Console → API Keys](https://www.glasswarp.com/console/keys) and re-export
    it. Never hardcode or commit keys.
  </Accordion>
</AccordionGroup>

## MCP (Claude / Cursor)

See [Connect via MCP](/get-started/mcp) for full setup.

<AccordionGroup>
  <Accordion title="Cursor MCP: Connection closed / ENOENT Cursor.app">
    Use an absolute `npx` path for your OS with the `mcp-remote` stdio bridge
    (macOS Apple Silicon `/opt/homebrew/bin/npx`, Intel `/usr/local/bin/npx`,
    Windows Node.js `npx` / `npx.cmd`, Linux typically `/usr/bin/npx`). Bare
    `npx` often fails inside Cursor.app. Details:
    [Connect via MCP](/get-started/mcp).
  </Accordion>

  <Accordion title="list_rigs returns fetch failed">
    Usually the MCP server could not reach the Platform API, or the client
    sent a placeholder key. Confirm the Platform API health endpoint and that
    `GLASSWARP_AUTH` is a real `gw_*` key.
  </Accordion>

  <Accordion title="Platform API hostname does not resolve">
    If `signal.glasswarp.com` (or your configured API base URL) fails to resolve
    on your machine, flush local DNS or try a public resolver (`1.1.1.1` /
    `8.8.8.8`). The MCP server reaches the API from its own network — local DNS
    only affects tools on your machine.
  </Accordion>

  <Accordion title="Tools listed but rig not usable">
    Host offline or API access off. Start the Windows agent; enable API access
    per-rig in the console.
  </Accordion>
</AccordionGroup>

## Rigs and sessions

<AccordionGroup>
  <Accordion title="No online rig with API access enabled">
    The host is offline, or API access is off. Open
    [Console → Rigs](https://www.glasswarp.com/console): confirm the rig is
    **online** and toggle **API access** on. This is the per-rig consent gate.
  </Accordion>

  <Accordion title="Request timeout">
    Verify the host stayed online (check the Console), then retry once. If it
    recurs, restart the host agent on the Windows machine.
  </Accordion>

  <Accordion title="Session seems stuck or usage keeps metering">
    Always `end_session` in a `finally` block. End stray sessions from
    **Console → Sessions**. `safety_restore` also runs on disconnect and
    `END_SESSION`.
  </Accordion>
</AccordionGroup>

## Live View

<AccordionGroup>
  <Accordion title="Live View looks washed or dull (screenshots look fine)">
    Windows **HDR / Advanced Color** was on. DXGI capture into the SDR WebRTC
    stream washes colors; GDI screenshots can still look correct.

    Glasswarp **auto-disables HDR for the API session** and restores it when the
    session ends. If colors are still wrong:

    1. Check **Console → Rigs** for an amber **HDR on** badge.
    2. On the Windows machine: **Settings → System → Display → HDR → Off**.
    3. Rebuild/restart the host agent so auto-disable is present.

    Dev opt-out only: `CAPTURE_ALLOW_HDR=1`. See [Live View](/guides/live-view).
  </Accordion>
</AccordionGroup>

## Input and vision

<AccordionGroup>
  <Accordion title="Drag or mouse_down/up not recognized">
    Update the Windows host agent — drag primitives require a host build with
    `mouse_down` / `mouse_up`. Current public release: **v0.2.21**
    ([Downloads](https://www.glasswarp.com/downloads)).
  </Accordion>

  <Accordion title="File menu / Save As / combo list items missing from targets">
    Host **v0.2.14+** merges popup HWNDs (menus, combo dropdowns) into the UIA
    snapshot. Confirm Console → Rigs shows `v0.2.14` or newer (auto-updates when
    idle), then reopen the menu and call `observe` again.
  </Accordion>

  <Accordion title="Clicks land in the wrong place">
    Stop guessing pixels. Use [grounding](/concepts/grounding): prefer
    `list_targets` / `click_target`, or Set-of-Mark via `observe(mark=True)`.
  </Accordion>

  <Accordion title="Screenshot works but the model misses targets">
    Use `observe()` (frame + dirty + targets) instead of a bare screenshot, and
    send a Set-of-Mark annotated frame so the model picks a target by id.
  </Accordion>
</AccordionGroup>

## Still stuck?

Check the [API reference](/api-reference/overview) for exact request/response shapes, or
watch the session live via [Live View](/guides/live-view) to see what the host
is actually doing.


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