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

# Troubleshooting

> Common issues and solutions for PandaProbe SDK

<AccordionGroup>
  <Accordion title="Traces not appearing in the dashboard">
    Possible causes:

    1. **Missing API key or project name** — The SDK requires both `PANDAPROBE_API_KEY` and `PANDAPROBE_PROJECT_NAME`. Without them, auto-initialization silently fails and no traces are sent.
    2. **Wrong endpoint** — If using a self-hosted instance, ensure `PANDAPROBE_ENDPOINT` points to your server.
    3. **SDK disabled** — Check that `PANDAPROBE_ENABLED` is not set to `false`.
    4. **Short-lived script** — Buffered traces may not flush before exit. Add Python's `pandaprobe.flush()` or TypeScript's `await flush()`.
    5. **Queue full** — If you're generating traces faster than they can be sent, older items are dropped. Increase `PANDAPROBE_MAX_QUEUE_SIZE` or `PANDAPROBE_BATCH_SIZE`.
  </Accordion>

  <Accordion title="Error: PandaProbe API key is required (TypeScript)">
    The TypeScript client throws this error when tracing is enabled but `PANDAPROBE_API_KEY` is absent. Set `PANDAPROBE_API_KEY`, pass `apiKey` to `init()`, or set `PANDAPROBE_ENABLED=false`.

    The project name is also required. Set `PANDAPROBE_PROJECT_NAME` or pass `projectName` to `init()`.
  </Accordion>

  <Accordion title="ValueError: PandaProbe API key is required">
    This error occurs when:

    * `PANDAPROBE_ENABLED` is `true` (the default)
    * But `PANDAPROBE_API_KEY` is not set

    Solutions:

    * Set the `PANDAPROBE_API_KEY` environment variable
    * Pass `api_key=` to `pandaprobe.init()`
    * Set `PANDAPROBE_ENABLED=false` if you don't want tracing in this environment
  </Accordion>

  <Accordion title="RuntimeError: No PandaProbe client available">
    This error occurs when calling `pandaprobe.start_trace()` without a configured client. The other convenience functions (`flush`, `shutdown`, `score`) silently no-op instead.

    Solutions:

    * Set `PANDAPROBE_API_KEY` and `PANDAPROBE_PROJECT_NAME` environment variables
    * Call `pandaprobe.init()` before using `start_trace()`
  </Accordion>

  <Accordion title="Traces are incomplete or missing spans">
    * Ensure all wrappers are called before making API calls: `client = wrap_openai(OpenAI())`
    * In TypeScript, wrap clients before use: `const client = wrapOpenAI(new OpenAI())`
    * For integrations, call `adapter.instrument()` once at startup before using the framework
    * For LangChain, LangGraph, and DeepAgents, pass the callback handler on every invocation
    * For Claude Agent SDK in TypeScript, call the wrapped function returned by `wrapClaudeAgentQuery()`
    * For Vercel AI, pass the model returned by `wrapLanguageModel()` to generation calls
    * Check for exceptions in span code — exceptions set span status to ERROR but the trace still completes
  </Accordion>

  <Accordion title="How to enable debug logging">
    ```bash theme={null}
    export PANDAPROBE_DEBUG=true
    ```

    Or programmatically:

    ```python title="Python" theme={null}
    pandaprobe.init(debug=True)
    ```

    ```ts title="TypeScript" theme={null}
    import { init } from "pandaprobe";
    init({ debug: true });
    ```

    This sets the `pandaprobe` logger to DEBUG level. You'll see detailed logs about initialization, span creation, transport batching, HTTP requests, and retry behavior.

    You can also configure the logger directly:

    ```python title="Python" theme={null}
    import logging
    logging.getLogger("pandaprobe").setLevel(logging.DEBUG)
    ```
  </Accordion>

  <Accordion title="Flushing in short-lived scripts">
    For scripts, notebooks, or Lambda functions that exit quickly:

    ```python title="Python" theme={null}
    import pandaprobe

    # ... your tracing code ...

    pandaprobe.flush()     # Block until all queued items are sent
    pandaprobe.shutdown()  # Release resources
    ```

    ```ts title="TypeScript" theme={null}
    import { flush, shutdown } from "pandaprobe";

    await flush();
    await shutdown();
    ```

    Python long-running services also flush through the background thread and `atexit` handler. In TypeScript services, call `shutdown()` from your process or framework shutdown hook for a deterministic final flush.
  </Accordion>

  <Accordion title="Queue full — dropping oldest item">
    This warning appears when the send queue reaches `PANDAPROBE_MAX_QUEUE_SIZE` (default: 1000). The oldest item is dropped to make room.

    Solutions:

    * Increase `PANDAPROBE_MAX_QUEUE_SIZE`
    * Increase `PANDAPROBE_BATCH_SIZE` for faster throughput
    * Decrease `PANDAPROBE_FLUSH_INTERVAL` for more frequent flushes
    * Check network connectivity to the PandaProbe backend
  </Accordion>
</AccordionGroup>


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