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

# Troubleshooting

> Common issues and fixes for the Detrics MCP server

## Claude Code issues

<AccordionGroup>
  <Accordion title="&#x22;detrics already exists&#x22; error">
    This happens when you try to add the Detrics MCP server but it is already registered.

    **Fix:** Remove the existing server first, then re-add it.

    ```bash theme={null}
    claude mcp remove detrics
    claude mcp add detrics-mcp https://mcp.detrics.io -e DETRICS_API_KEY=your-api-key -t streamable-http
    ```
  </Accordion>

  <Accordion title="&#x22;DETRICS_API_KEY is required&#x22; error">
    The MCP server started but could not find your API key in the environment.

    **Causes:**

    * The API key was not passed correctly when adding the server
    * The environment variable name was misspelled

    **Fix:** Remove and re-add the server, making sure the `-e DETRICS_API_KEY=...` flag is included with your full API key.
  </Accordion>

  <Accordion title="&#x22;Unauthorized&#x22; or invalid key error">
    The API key was provided but is not valid.

    **Causes:**

    * The key was revoked from the web app
    * The key was copied incorrectly (missing characters)
    * The key belongs to a different workspace

    **Fix:**

    1. Check if the key is still active at [app.detrics.io/mcp](https://app.detrics.io/mcp)
    2. If revoked, generate a new key and update Claude Code (see [Claude Code](/claude/claude-code#updating-your-api-key))
    3. Make sure you are using a key from the correct workspace
  </Accordion>
</AccordionGroup>

## Claude Web OAuth issues

<AccordionGroup>
  <Accordion title="&#x22;Authorization failed&#x22; or stuck on login page">
    This usually happens when the OAuth flow is interrupted.

    **Fix:**

    1. Clear your browser cookies and try again
    2. Make sure your Detrics account is active at [app.detrics.io](https://app.detrics.io)
    3. Try opening the connection flow in a private/incognito window
    4. Make sure you are on a supported plan (Claude Pro or higher)
  </Accordion>

  <Accordion title="&#x22;Connection error&#x22; when adding the MCP server URL">
    The server URL was entered incorrectly.

    **Fix:** The URL must be exactly:

    ```
    https://mcp.detrics.io
    ```

    Enter the base URL by itself, with no trailing slash, no `/sse` suffix, and no `/mcp` path.
  </Accordion>

  <Accordion title="Claude cannot access Detrics tools">
    The MCP connection may have expired or been removed.

    **Fix:**

    1. Go to Claude **Settings > Connections**
    2. Remove the existing Detrics connection
    3. Reconnect from [app.detrics.io/mcp/claude](https://app.detrics.io/mcp/claude)
  </Accordion>
</AccordionGroup>

## Data query issues

<AccordionGroup>
  <Accordion title="&#x22;No connections found&#x22; response">
    Claude can reach Detrics, but there are no platforms connected in your workspace.

    **Fix:**

    1. Go to [app.detrics.io](https://app.detrics.io) and connect at least one data source
    2. Or ask Claude: "Connect my Facebook Ads account", it will generate an OAuth link for you
  </Accordion>

  <Accordion title="&#x22;Unknown platform_api&#x22; error">
    The platform identifier used in the query does not match any supported platform.

    **Fix:** Use the exact platform identifiers. Ask Claude: "List my connections" to see the correct `platform_api` values for your connected platforms.

    Common identifiers include: `facebook_ads`, `google_ads`, `tiktok_ads`, `shopify`, `google_analytics_4`, `linkedin_ads`, `pinterest_ads`, `bing_ads`, `stripe`.
  </Accordion>

  <Accordion title="Fields not found or invalid field error">
    The metric or dimension name used in a query does not exist for that platform.

    **Fix:** Ask Claude to list available fields first:

    ```
    What metrics and dimensions are available for Google Ads?
    ```

    This calls `list_fields` and returns all valid field names for the platform.
  </Accordion>
</AccordionGroup>

## Still need help?

<Card title="Chat with Support" icon="comments" href="https://support.detrics.io/chat">
  Reach out to our support team for help with any issues not covered here.
</Card>