> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/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.

> [accordion] 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] 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. In v0.49.0 and later, long-lived processes wait up to 1 second to batch nearby rows. Normal process exit flushes pending logs, but signals and `os._exit()` bypass Python exit handlers.
>
> **Fix:** Call `logger.flush()` before terminating the process. To disable the batching delay, set [`BRAINTRUST_FLUSH_DELAY_MS`](https://docs.braintrust.dev/sdks/python/api-reference#environment-variables) to `0`.
>
> ```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()
> ```
>
> Check for logging failures after flushing. See [Trace data durability](https://docs.braintrust.dev/instrument.md#trace-data-durability) for the API's storage guarantee.

> [accordion] 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] 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()
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.