Traces are missing or provider calls are not traced
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.Events are missing from short-lived scripts or jobs
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 Check for logging failures after flushing. See Trace data durability for the API’s storage guarantee.
os._exit() bypass Python exit handlers.Fix: Call logger.flush() before terminating the process. To disable the batching delay, set BRAINTRUST_FLUSH_DELAY_MS to 0.API key is not picked up
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.Traces are empty, incomplete, or stuck in progress
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.Prompt shows None in experiment view
Prompt shows None in experiment view
Issue: The experiment view shows
Prompt: None, even though your task uses a prompt.Cause: The UI detects prompts from prompt metadata on LLM spans. Hard-coded prompts, or prompts sent without the Braintrust prompt workflow, don’t attach that metadata.Fix: Load the prompt with load_prompt(), call prompt.build() to produce the request parameters, and send them through a wrapped or auto-instrumented client. The wrapper reads the metadata from build() and attaches it to the LLM span.Prompt version IDs do not match the UI
Prompt version IDs do not match the UI
For TypeScript, see the Prompt version IDs do not match the UI section in TypeScript troubleshooting.Issue:
prompt.version returns a large decimal string, while the Braintrust UI shows a short hexadecimal version ID.Cause: The SDK returns the raw transaction ID. The UI displays a shorter, reversible encoding of the same ID.Fix: Convert between the two forms with prettify_xact() and load_pretty_xact(). Import both from braintrust.xact_ids, not the top-level braintrust package. load_prompt() accepts either form as version.