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

# Troubleshooting

> Common issues, setup help, and frequently asked questions

## Integration Issues

<AccordionGroup>
  <Accordion title="Struct not responding in Slack">
    Ensure `@Struct` is invited to the channel and the Slack integration is connected in **Connections**. Struct can only monitor and respond in channels where it has been explicitly invited.
  </Accordion>

  <Accordion title="Alerts not triggering investigations">
    Check that your alerting source (Sentry, Datadog) is connected in **Connections** and the correct projects/services are selected. For issue tracker triggers (Linear), ensure the issue is assigned to Struct or Struct is @tagged in a comment.
  </Accordion>

  <Accordion title="Struct can't access my repository">
    Go to **Connections** → **GitHub** → **Manage Repositories** and ensure the repo is selected. Some organizations require admin approval for third-party apps.
  </Accordion>

  <Accordion title="Log queries returning empty results">
    Verify your cloud log provider credentials have sufficient read permissions. Check that the correct region, log group, or workspace is configured. See [Connections](/connections#cloud-log-providers) for setup details.
  </Accordion>

  <Accordion title="Sentry errors not found during investigation">
    Verify the Sentry organization is selected in **Connections** → **Sentry** and your token has read access to the relevant projects.
  </Accordion>

  <Accordion title="Observability platform not connecting">
    Double-check that API keys or credentials have the required read permissions. For Grafana, ensure the API key has at least Viewer access. For Datadog, ensure both API and application keys are provided, and that the application key's role grants the `logs_read_data`, `timeseries_query`, `monitors_read`, and `dashboards_read` scopes. A `403 Forbidden` on metric queries specifically (while logs work) usually means the role is missing `timeseries_query`.
  </Accordion>
</AccordionGroup>

***

## Investigation Issues

<AccordionGroup>
  <Accordion title="Investigation takes too long">
    Normal investigation time is **under 5 minutes**. Complex issues with large codebases or many log sources may take longer. Check the Struct dashboard for status. If investigations consistently take too long, try narrowing the scope of connected log sources.
  </Accordion>

  <Accordion title="Investigation report seems incomplete">
    The more integrations connected, the richer the investigation. Ensure relevant observability platforms and cloud log providers are connected. Struct produces the best results when it can cross-reference multiple signal sources.
  </Accordion>

  <Accordion title="Root cause analysis seems inaccurate">
    Struct improves over time as it processes more alerts. Ensure all relevant data sources are connected. You can ask follow-up questions in the Slack thread to refine the analysis—Struct maintains full context throughout the conversation.
  </Accordion>

  <Accordion title="PR not being created after approval">
    Check that [GitHub](/connections#github) is connected with write access. Common causes: branch protection rules, signed commit requirements, or permissions issues. Try reconnecting GitHub in **Connections**.
  </Accordion>

  <Accordion title="Tests failing in a created PR">
    Struct runs your existing test suite via [configured scripts](/build-agent#prepost-execution-scripts). Review the test output in the PR and request changes if needed.
  </Accordion>
</AccordionGroup>

***

## MCP & CLI Bridge Issues

<AccordionGroup>
  <Accordion title="MCP server not connecting in Claude Code">
    Verify you ran the correct install command from **Settings** → **Coding Agent** → **Claude Code**. The command should look like:

    ```bash theme={null}
    claude mcp add --transport http struct <your-mcp-url>
    ```

    Make sure you're using the MCP URL shown in your settings page, and that you've logged in with `struct login` at least once.
  </Accordion>

  <Accordion title="MCP server not connecting in Cursor">
    Try the one-click install button in **Settings** → **Coding Agent** → **Cursor**. If that doesn't work, manually add the config to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "struct": {
          "url": "<your-mcp-url>"
        }
      }
    }
    ```

    You can find your MCP URL in **Settings** → **Coding Agent** → **Cursor**.
  </Accordion>

  <Accordion title="MCP tools returning authentication errors">
    OAuth login is triggered automatically on first MCP tool use. If authentication fails, try running `struct login` from your terminal to re-authenticate, then retry in your coding agent.
  </Accordion>

  <Accordion title="'Open in Claude Code' / 'Open in Cursor' not working">
    This requires the CLI bridge to be installed. Run:

    ```bash theme={null}
    npm install -g @struct/cli
    struct bridge install
    ```

    If you've already installed it, try `struct bridge uninstall` followed by `struct bridge install` to re-register the protocol handler.
  </Accordion>

  <Accordion title="'struct' command not found">
    Ensure the CLI is installed globally:

    ```bash theme={null}
    npm install -g @struct/cli
    ```

    If you use `nvm`, `fnm`, or another Node version manager, make sure the global `bin` directory is in your `PATH`. Try opening a new terminal window after installation.
  </Accordion>

  <Accordion title="CLI bridge installed but browser doesn't open agent">
    On macOS, the bridge registers as a native app. Try restarting your browser after installation. If using Chrome, you may need to allow the `struct://` protocol when prompted.

    On Linux, ensure `xdg-mime` is available and the `.desktop` file was created correctly. Run `struct bridge install` again to re-register.
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="What is Struct?">
    Struct is an AI support engineer that automatically investigates on-call engineering alerts. It cross-references logs, metrics, traces, and the codebase to determine root cause, assess impact, and suggest fixes — before you start debugging.
  </Accordion>

  <Accordion title="What is the free plan?">
    Struct offers a free plan that includes monthly credits so you can start investigating immediately — no credit card required. You can upgrade to a paid plan anytime for more credits and higher limits. See [Usage & Credits](/usage-and-credits) for details.
  </Accordion>

  <Accordion title="What are credits?">
    Credits are consumed when Struct runs investigations. Your plan includes a monthly credit allowance that resets each billing cycle. You can also purchase top-up credits that roll over indefinitely. See [Usage & Credits](/usage-and-credits) for details.
  </Accordion>

  <Accordion title="What is Ask Struct?">
    Ask Struct is a natural language interface for querying your production systems. Ask about alerts, logs, metrics, or code — and Struct gathers context across your connected tools to deliver answers. Try it at [Ask Struct](https://app.struct.ai/ask). See [Ask Struct](/ask-struct) for more.
  </Accordion>

  <Accordion title="How do I set up the MCP server?">
    Go to **Settings** → **Coding Agent** in the web app and follow the instructions for your coding agent (Claude Code or Cursor). See [Open in Claude Code / Cursor](/open-in-agent#set-up-mcp) for details.
  </Accordion>

  <Accordion title="How do I install the CLI bridge?">
    Run `npm install -g @struct/cli` then `struct bridge install`. This enables one-click "Open in" buttons from the web app. See [Open in Claude Code / Cursor](/open-in-agent#install-the-cli-bridge) for details.
  </Accordion>

  <Accordion title="How is Struct different from ChatGPT, Claude, Codex, or Devin?">
    General-purpose coding agents require manual log retrieval, custom orchestration, and observability integration to debug production issues.

    Struct is **already integrated** with your observability stack. It automatically collects production data, builds structured investigations, maintains historical intelligence, and provides secure tenant isolation.

    **Struct investigates. Coding agents implement.** They are complementary—Struct provides the production-grounded context, and coding agents generate the code.
  </Accordion>

  <Accordion title="Does Struct improve over time?">
    Yes. Struct builds on-call intelligence from past alerts and investigations, enabling pattern recognition and faster root cause detection. The more issues it processes, the more accurate investigations become.
  </Accordion>

  <Accordion title="Can Struct generate pull requests?">
    Yes. After an investigation, you can approve a fix and the [Struct Build Agent](/build-agent) will create a branch, implement the changes, run tests, and open a PR. You can also [open in Claude Code or Cursor](/open-in-agent) with full investigation context.
  </Accordion>

  <Accordion title="Does Struct store my code?">
    No. Code is read during analysis but not permanently stored. All data is encrypted and logically isolated per customer. Struct is SOC2 Type II and HIPAA compliant.
  </Accordion>

  <Accordion title="Does Struct work with my observability stack?">
    Struct integrates with Sentry, Datadog, Grafana, Prometheus, Loki, SumoLogic, Render, AWS CloudWatch, Azure Monitor, Google Cloud Logging, Slack, Linear, Asana, and GitHub. New integrations can be built in days.
  </Accordion>

  <Accordion title="How fast can Struct be set up?">
    You can be up and running in under 5 minutes with the free plan. Connect GitHub, connect Slack, and start investigating.
  </Accordion>

  <Accordion title="Who is Struct for?">
    * Engineering teams with on-call rotations
    * Teams with heavy alert loads
    * Organizations wanting automated root cause analysis
    * Teams using coding agents who want structured production context
    * Companies where uptime and reliability are critical (fintech, payments, healthcare, etc.)
  </Accordion>

  <Accordion title="GitLab or Bitbucket support?">
    Currently GitHub only. Other providers are on the roadmap.
  </Accordion>

  <Accordion title="How do I cancel an investigation?">
    Go to the investigation in the Struct dashboard and click **Cancel**.
  </Accordion>
</AccordionGroup>

***

## Contact Support

Email us at [help@struct.ai](mailto:help@struct.ai)