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

# Troubleshooting

> Diagnose and fix common issues when installing or using the Braintrust Ruby SDK.

This page outlines common issues when setting up and using the Braintrust Ruby SDK and how to resolve them.

<AccordionGroup>
  <Accordion title="No traces after adding braintrust/setup to the Gemfile">
    Verify that your app loads Bundler before application code:

    ```ruby theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    require "bundler/setup"
    Bundler.require
    ```

    Rails applications do this during boot. Add it explicitly for Sinatra, Rack, and custom Ruby processes that do not load Bundler before application code.

    You can also require the setup file directly from an application initializer:

    ```ruby theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    require "braintrust/setup"
    ```
  </Accordion>

  <Accordion title="No traces from a short-lived script">
    For scripts that exit immediately after an AI call, force OpenTelemetry to flush before the process exits:

    ```ruby theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    OpenTelemetry.tracer_provider.shutdown
    ```

    `braintrust/setup` also registers an exit hook by default. If `BRAINTRUST_FLUSH_ON_EXIT=false` is set, remove that setting or flush manually.
  </Accordion>

  <Accordion title="An integration is not being auto-instrumented">
    Confirm that the provider gem is installed and loaded in the process. Auto-instrumentation only patches integrations that are available when setup runs.

    You can instrument a provider explicitly after requiring it:

    ```ruby theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    require "braintrust"
    require "openai"

    Braintrust.init(auto_instrument: false)
    Braintrust.instrument!(:openai)
    ```

    If you use integration filters, check `BRAINTRUST_INSTRUMENT_ONLY`, `BRAINTRUST_INSTRUMENT_EXCEPT`, `braintrust exec --only`, and `braintrust exec --except`.
  </Accordion>

  <Accordion title="Traces are written to the wrong project">
    Set the default project in the environment:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    BRAINTRUST_DEFAULT_PROJECT="My project"
    ```

    Or pass it when initializing the SDK:

    ```ruby theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    Braintrust.init(default_project: "My project")
    ```
  </Accordion>

  <Accordion title="Debug setup and API errors">
    Enable SDK debug logging:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    BRAINTRUST_DEBUG=true
    ```

    The SDK logs setup failures, auto-instrumentation decisions, and API request errors to help identify missing API keys, login failures, or provider loading issues.
  </Accordion>
</AccordionGroup>