Troubleshooting

Traces not appearing in the dashboard

Possible causes:

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.
Wrong endpoint — If using a self-hosted instance, ensure PANDAPROBE_ENDPOINT points to your server.
SDK disabled — Check that PANDAPROBE_ENABLED is not set to false.
Short-lived script — Buffered traces may not flush before exit. Add Python’s pandaprobe.flush() or TypeScript’s await flush().
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.

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().

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

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()

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

How to enable debug logging

export PANDAPROBE_DEBUG=true

Or programmatically:

Python

pandaprobe.init(debug=True)

TypeScript

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

import logging
logging.getLogger("pandaprobe").setLevel(logging.DEBUG)

Flushing in short-lived scripts

For scripts, notebooks, or Lambda functions that exit quickly:

Python

import pandaprobe

# ... your tracing code ...

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

TypeScript

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.

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

Get Started

Tracing