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

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

<AccordionGroup>
  <Accordion title="No traces appear in Braintrust">
    For manual instrumentation, initialize Braintrust with `Braintrust.get()` and `openTelemetryCreate()` before you create your provider client, and make calls on the **wrapped** client returned by the wrap method:

    ```java #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    var braintrust = Braintrust.get();
    var openTelemetry = braintrust.openTelemetryCreate();

    // Trace calls on `client`, not on a separately constructed client
    OpenAIClient client = BraintrustOpenAI.wrapOpenAI(openTelemetry, OpenAIOkHttpClient.fromEnv());
    ```

    For auto-instrumentation, confirm the Java Agent is attached at startup (see below).
  </Accordion>

  <Accordion title="Auto-instrumentation isn't tracing anything">
    The Java Agent only instruments when it's attached via the `-javaagent` JVM flag at startup. Verify the flag is on the command (or `jvmArgs`) that actually launches your app.

    If you run with other Java agents, add the Braintrust agent **last** in the argument list:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    java -javaagent:/path/to/other-agent.jar -javaagent:/path/to/braintrust-java-agent.jar -jar app.jar
    ```
  </Accordion>

  <Accordion title="Traces are written to the wrong project">
    Spans route to `BRAINTRUST_DEFAULT_PROJECT_NAME`, which defaults to `default-java-project` when unset. Set the project in the environment:

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

    Or pass it through configuration:

    ```java #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    var config = BraintrustConfig.builder()
        .defaultProjectName("My project")
        .build();
    var braintrust = Braintrust.get(config);
    ```
  </Accordion>

  <Accordion title="BRAINTRUST_API_KEY is required error">
    The SDK reads your API key from the `BRAINTRUST_API_KEY` environment variable, or from an API key set on the config builder. Set the variable:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    BRAINTRUST_API_KEY="your-api-key"
    ```

    Or provide it explicitly:

    ```java #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    var config = BraintrustConfig.builder()
        .apiKey(System.getenv("BRAINTRUST_API_KEY"))
        .build();
    var braintrust = Braintrust.get(config);
    ```
  </Accordion>

  <Accordion title="Debug setup and API errors">
    The SDK logs to the `dev.braintrust` namespace through SLF4J. Enable debug logging to surface configuration and export issues. With `slf4j-simple`, set:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    -Dorg.slf4j.simpleLogger.log.dev.braintrust=DEBUG
    ```

    You can also enable SDK debug mode and console trace logging via environment variables:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    BRAINTRUST_DEBUG=true
    BRAINTRUST_ENABLE_TRACE_CONSOLE_LOG=true
    ```
  </Accordion>
</AccordionGroup>