> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/badrisnarayanan/antigravity-claude-proxy/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for Antigravity Claude Proxy

## Common Issues

<AccordionGroup>
  <Accordion title="Windows: OAuth Port Error (EACCES)">
    On Windows, the default OAuth callback port (51121) may be reserved by Hyper-V, WSL2, or Docker. If you see:

    ```
    Error: listen EACCES: permission denied 0.0.0.0:51121
    ```

    The proxy will automatically try fallback ports (51122-51126). If all ports fail, try these solutions:

    ### Option 1: Use a Custom Port (Recommended)

    Set a custom port outside the reserved range:

    ```bash theme={null}
    # Windows PowerShell
    $env:OAUTH_CALLBACK_PORT = "3456"
    antigravity-claude-proxy start

    # Windows CMD
    set OAUTH_CALLBACK_PORT=3456
    antigravity-claude-proxy start

    # Or add to your .env file
    OAUTH_CALLBACK_PORT=3456
    ```

    ### Option 2: Reset Windows NAT

    Run as Administrator:

    ```powershell theme={null}
    net stop winnat
    net start winnat
    ```

    ### Option 3: Check Reserved Ports

    See which ports are reserved:

    ```powershell theme={null}
    netsh interface ipv4 show excludedportrange protocol=tcp
    ```

    If 51121 is in a reserved range, use Option 1 with a port outside those ranges.

    ### Option 4: Permanently Exclude Port (Admin)

    Reserve the port before Hyper-V claims it (run as Administrator):

    ```powershell theme={null}
    netsh int ipv4 add excludedportrange protocol=tcp startport=51121 numberofports=1
    ```

    <Note>
      The server automatically tries fallback ports (51122-51126) if the primary port fails.
    </Note>
  </Accordion>

  <Accordion title="Could not extract token from Antigravity">
    If using single-account mode with Antigravity:

    1. Make sure Antigravity app is installed and running
    2. Ensure you're logged in to Antigravity

    Or add accounts via OAuth instead:

    ```bash theme={null}
    antigravity-claude-proxy accounts add
    ```
  </Accordion>

  <Accordion title="401 Authentication Errors">
    The token might have expired. Try refreshing:

    ```bash theme={null}
    curl -X POST http://localhost:8080/refresh-token
    ```

    Or re-authenticate the account:

    ```bash theme={null}
    antigravity-claude-proxy accounts
    ```
  </Accordion>

  <Accordion title="Rate Limiting (429)">
    With multiple accounts, the proxy automatically switches to the next available account. With a single account, you'll need to wait for the rate limit to reset.

    The proxy uses smart account selection strategies to minimize rate limiting:

    * **Sticky**: Stays on same account (best for caching)
    * **Round-Robin**: Rotates every request (best for throughput)
    * **Hybrid**: Smart distribution based on health and quotas (default)
  </Accordion>

  <Accordion title="Account Shows as Invalid">
    Re-authenticate the account:

    ```bash theme={null}
    antigravity-claude-proxy accounts
    # Choose "Re-authenticate" for the invalid account
    ```
  </Accordion>

  <Accordion title="403 Permission Denied / VALIDATION_REQUIRED">
    If you see:

    ```
    403 VALIDATION_REQUIRED - Account requires verification
    ```

    This means Google requires your account to complete verification (phone number, captcha, or terms acceptance).

    **The proxy handles this automatically:**

    1. The affected account is marked invalid and the proxy rotates to the next available account
    2. If a verification URL is provided by Google, it's stored and shown in the WebUI
    3. Other accounts continue working normally while the affected account is paused

    **To fix the affected account:**

    1. Open the WebUI at [http://localhost:8080](http://localhost:8080)
    2. Find the account marked with an error badge
    3. Click the **FIX** button - this opens the Google verification page directly
    4. Complete the verification (phone number, captcha, etc.)
    5. Click the **↻ Refresh** button on the account to re-enable it

    **If the FIX button opens an OAuth page instead** (no verification URL was provided), re-authenticate the account:

    ```bash theme={null}
    antigravity-claude-proxy accounts
    # Choose "Re-authenticate" for the invalid account
    ```

    **If all accounts are invalid**, the proxy returns an error immediately instead of waiting indefinitely:

    ```
    All accounts are invalid: Account requires verification. Visit the WebUI to fix them.
    ```

    <Note>
      Verification errors persist across server restarts until resolved. Auth errors (token revoked/expired) are reset on restart and require OAuth re-authentication via the FIX button.
    </Note>
  </Accordion>
</AccordionGroup>