> ## 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">
    The public PyPI release may not be live yet. Do **not** install a
    similarly named package. Use the approved package artifact, or inside the
    monorepo install the local SDK: `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>

## 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>

## 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`.
  </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.