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

# Troubleshooting

> Common issues and solutions for the Databrain MCP server

## Common Issues

<AccordionGroup>
  <Accordion title="Missing token configuration" icon="key">
    **Cause:** Neither `DATABRAIN_SERVICE_TOKEN` nor `DATABRAIN_API_TOKEN` is set, or your MCP client is not reading the configured `env` block.

    **Fix:**

    1. Check that your token is in the `env` block of your MCP config.
    2. Verify the token value has no extra spaces or quotes.
    3. Restart your AI client after changing the config.

    ```json theme={"dark"}
    {
      "mcpServers": {
        "databrain": {
          "command": "npx",
          "args": ["@databrainhq/mcp-server"],
          "env": {
            "DATABRAIN_SERVICE_TOKEN": "your-actual-token-here"
          }
        }
      }
    }
    ```

    If the token is set correctly and the error persists, regenerate it in **Settings -> Service Tokens** in the Databrain UI.
  </Accordion>

  <Accordion title="API-token-only mode cannot run setup tools" icon="key">
    **Cause:** You configured only `DATABRAIN_API_TOKEN`. API tokens are scoped to one data app and cannot run org-level setup tools.

    **Fix:** Add `DATABRAIN_SERVICE_TOKEN` when you need discovery, data app management, API token creation, semantic layer operations, or datamart setup.

    API-token-only mode is still valid for embed operations, widget operations, guest tokens, demo links, and scheduled report metadata inside the configured data app.
  </Accordion>

  <Accordion title="No dashboards found" icon="table-columns">
    **Cause:** No workspace was selected, the selected workspace has no dashboards, or the configured token is scoped too narrowly.

    **Fix:** Ask the assistant:

    > "List my workspaces and then show dashboards"

    Dashboards are usually scoped to workspaces. If you see workspaces but no dashboards, verify that dashboards exist in the Databrain UI for that workspace.
  </Accordion>

  <Accordion title="Embed not rendering in frontend" icon="window-maximize">
    **Cause:** Usually a token, ID, domain, or guest token payload mismatch.

    **Fix:**

    1. **Guest token generated server-side?** Never expose API tokens in frontend code.
    2. **IDs match?** Verify the embed ID and dashboard ID.
    3. **Domain whitelisted?** Check that your frontend's domain is allowed in the data app settings.
    4. **Inspect the embed:** Ask the assistant:

    > "Check my embed configuration for issues"

    The assistant uses `get_embed_details` to inspect access settings, dashboard references, and token inputs.
  </Accordion>

  <Accordion title="Theme or option changes not showing" icon="palette">
    **Cause:** Existing guest tokens may still carry old configuration.

    **Fix:** After updating theme or options through `customize_embed_theme` or `update_embed`:

    1. Regenerate the guest token with `generate_guest_token`.
    2. Reload your application to use the new token.

    Guest tokens are generated server-side and should be refreshed after configuration changes that affect runtime behavior.
  </Accordion>

  <Accordion title="Widget changes do not appear in preview" icon="chart-line">
    **Cause:** The widget may be unpublished, the preview is using a stale guest token, or the wrong `clientId` was used.

    **Fix:**

    1. Ask the assistant to call `list_widgets` for the target `clientId` and dashboard.
    2. Confirm the widget has `isPublished: true` if it should appear to end users.
    3. Generate a fresh `get_demo_link` URL.
    4. If testing inside your own app, regenerate the app's guest token.
  </Accordion>

  <Accordion title="SQL-to-metric apply is rejected" icon="shield">
    **Cause:** Production writes require an explicit confirmation value.

    **Fix:** Run the dry-run first, review the returned plan, then apply only after approval:

    ```json theme={"dark"}
    {
      "mode": "apply",
      "confirm": "APPLY_TO_PRODUCTION"
    }
    ```

    This applies to `create_or_update_metric_from_query` and production datamart creation through `create_datamart`.
  </Accordion>

  <Accordion title="ask_question returns poor results" icon="magnifying-glass-chart">
    **Cause:** The semantic layer is empty, incomplete, or missing business context.

    **Fix:** Check its status:

    > "Check the semantic layer quality for my datamart"

    If descriptions or synonyms are missing, ask:

    > "Add descriptions and synonyms to improve query accuracy"

    The assistant can update metadata with `update_semantic_layer` or start semantic-layer generation with `start_semantic_layer_generation`.
  </Accordion>

  <Accordion title="Server won't start" icon="server">
    **Cause:** Usually a Node.js version issue or invalid environment variable.

    **Fix:** The MCP server requires Node.js 18 or higher:

    ```bash theme={"dark"}
    node --version
    ```

    If you see a version below 18, update Node.js. Also verify `DATABRAIN_API_URL` and `DATABRAIN_DEMO_DOMAIN` are valid URLs when set.
  </Accordion>

  <Accordion title="npx command not found or hangs" icon="terminal">
    **Cause:** npm/npx is not installed or the client cannot fetch the package.

    **Fix:**

    1. Ensure npm is installed: `npm --version`
    2. Try running the package directly:

    ```bash theme={"dark"}
    npx @databrainhq/mcp-server
    ```

    3. If fetching the package hangs, install globally:

    ```bash theme={"dark"}
    npm install -g @databrainhq/mcp-server
    ```

    Then update your config to use the global binary:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "databrain": {
          "command": "databrain-mcp-server",
          "env": {
            "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Diagnostics

Ask your assistant:

> "Who am I authenticated as in Databrain?"

This calls `whoami` and confirms whether the session is using a service token or API token.

For embed issues, ask:

> "Check my embed configuration for issues"

The assistant uses `get_embed_details` to inspect access settings and dashboard references, then regenerates a guest token if runtime state changed.

For customer dashboard issues, ask:

> "List widgets for this client and give me a demo link"

The assistant uses `list_widgets` and `get_demo_link`.

***

## Known Limitations

| Area                  | Limitation                                                                | Workaround                                                                                                               |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Datasource setup**  | Datasources are connected in the Databrain UI                             | Create datasources in the Databrain UI, then use `list_datasources`, `discover_datasource_schema`, and `sync_datasource` |
| **Workspace setup**   | Workspaces are created in the Databrain UI                                | Create workspaces in the Databrain UI, then use `list_workspaces` and dashboard workflows                                |
| **Transport**         | stdio only; no HTTP/SSE transport yet                                     | Use `npx` with your MCP client's config file                                                                             |
| **Production writes** | Datamart and SQL-to-metric apply operations require explicit confirmation | Run dry-run first, review the plan, then apply with `confirm: "APPLY_TO_PRODUCTION"`                                     |
| **Scheduled reports** | `list_scheduled_reports` returns configured schedule metadata             | Use Databrain reporting views for delivery status                                                                        |

***

## Getting Help

<CardGroup cols={3}>
  <Card title="Quickstart" icon="bolt" href="/developer-docs/mcp-server/quickstart">
    Start over with setup
  </Card>

  <Card title="Client Setup" icon="gear" href="/developer-docs/mcp-server/client-setup">
    Verify your client config
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/developer-docs/mcp-server/tools-reference">
    Review available tools
  </Card>
</CardGroup>