> ## 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 Python SDK.

<AccordionGroup>
  <Accordion title="Traces are missing or provider calls are not traced">
    **Issue:** Your application runs successfully, but LLM calls do not appear in Braintrust.

    **Cause:** `auto_instrument()` must run after `init_logger()` and before creating AI provider clients. Clients created first may not be patched for tracing.

    **Fix:** Initialize Braintrust as early as possible during application startup, then create your provider clients.

    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import braintrust
    from openai import OpenAI

    logger = braintrust.init_logger(project="My Project")
    braintrust.auto_instrument()

    client = OpenAI()
    ```
  </Accordion>

  <Accordion title="Events are missing from short-lived scripts or jobs">
    **Issue:** A script, notebook cell, background job, or CLI finishes but some events never appear in Braintrust.

    **Cause:** The SDK buffers logs before sending them. A short-lived process can exit before the buffer flushes.

    **Fix:** Call `logger.flush()` before the process exits.

    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import braintrust

    logger = braintrust.init_logger(project="My Project")
    braintrust.auto_instrument()

    # Run your work here.

    logger.flush()
    ```
  </Accordion>

  <Accordion title="API key is not picked up">
    **Issue:** Logging fails with an authentication error, or traces do not appear in the expected organization.

    **Cause:** `BRAINTRUST_API_KEY` is missing from the environment of the process that runs your Python code.

    **Fix:** Set `BRAINTRUST_API_KEY` in the same shell, service, notebook, container, or deployment environment that starts your app.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    export BRAINTRUST_API_KEY="your-api-key"
    python app.py
    ```
  </Accordion>

  <Accordion title="Traces are empty, incomplete, or stuck in progress">
    **Issue:** A trace appears but is missing final values, or a manually-created span never finishes.

    **Cause:** A process can exit before logs flush, or an exception can bypass the end of a manually-created span.

    **Fix:** Prefer `traced`, which handles span lifecycle for you. If you create spans manually, make sure they are ended and flushed even when an exception occurs.

    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import braintrust

    logger = braintrust.init_logger(project="My Project")

    @braintrust.traced
    def classify_text(text: str) -> str:
        return "positive"

    classify_text("Great result")
    logger.flush()
    ```
  </Accordion>
</AccordionGroup>