Troubleshooting

Traces not appearing in the dashboard

Symptom: You initialized the SDK and made LLM calls, but the dashboard shows no data after 15–30 seconds.

Wrong or missing API key

Verify the API key you passed to init() starts with zsp_ and matches the one shown in Settings → API Keys for your project. A typo or a key from a different project will cause all events to be silently dropped (the SDK logs a warning, but does not throw).Enable debug: true to see SDK activity:

zespan.init({
  apiKey: process.env.ZESPAN_API_KEY!,
  debug: true, // logs flush success/failure to console
});

Process exited before flush

The SDK batches events and flushes them every 2 seconds by default. If your script or Lambda handler exits before the flush fires, events are lost. Call flush() explicitly before the process ends:

TypeScript
Python

await zespan.getClient().flush();

zespan.get_client().flush()

See the Serverless guide for environment-specific patterns.

Wrong baseURL

If you self-host Zespan, make sure you set baseURL to your API server’s address. The default is https://api.zespan.com.

zespan.init({
  apiKey: "zsp_...",
  baseURL: "https://api.yourdomain.com",
});

Firewall or proxy blocking outbound requests

The SDK sends events to https://api.zespan.com over HTTPS (port 443). If your environment blocks outbound traffic, allowlist this endpoint. Use debug: true to see if flush requests are failing with network errors.

SDK not initialized before LLM call

zespan.init() must be called before any wrapped LLM client is created.

// ✓ Correct — init before wrap
zespan.init({ apiKey: "zsp_..." });
const openai = zespan.wrapOpenAI(new OpenAI());

// ✗ Wrong — wrap before init
const openai = zespan.wrapOpenAI(new OpenAI());
zespan.init({ apiKey: "zsp_..." });

Cost showing $0.00 for all events

Symptom: Traces appear in the dashboard but the cost_usd column is always zero.

Model name not in the pricing table

The SDK computes cost from a built-in pricing table keyed on the exact model string. If you use a model ID the SDK doesn’t recognise, cost_usd is set to 0 rather than throwing an error.Check your model strings against the supported models reference. Common mismatches:

You send	SDK expects
`gpt4o`	`gpt-4o`
`claude-3-5-sonnet`	`claude-3-5-sonnet-20241022`
`gemini-pro`	`gemini-1.5-pro`

If you use a model not in the table, open an issue on GitHub — we add new models with each release.

Token counts are zero

If input_tokens or output_tokens are 0, cost will also be 0. This can happen if the provider response doesn’t include usage data — for example, streaming calls where you don’t consume the full stream before closing it.For streaming calls, make sure you iterate the full response before the function returns:

const stream = await openai.chat.completions.create({ stream: true, ... });
for await (const chunk of stream) {
  // consume every chunk
}
// Usage data is in the final chunk — the SDK captures it automatically

Parent-child spans not linking (broken trace tree)

Symptom: Multi-step agent workflows show as separate disconnected traces instead of a nested tree.

Context not propagated across async boundaries

The SDK propagates trace context automatically through async calls. If you break the async chain — for example, by using setTimeout, setImmediate, or a non-async callback — context is lost.Always use await for async operations inside withZespanContext or withAgent:

// ✓ Context propagates correctly
await withAgent({ name: "MyAgent" }, async (agent) => {
  await agent.traceTool("fetch-data", {}, () => fetchData());
});

// ✗ Context is lost inside setTimeout
await withAgent({ name: "MyAgent" }, async (agent) => {
  setTimeout(() => fetchData(), 0); // no await — context is dropped
});

withZespanContext missing in request handler

If you call wrapped LLM clients outside a withZespanContext block, each call gets its own isolated trace context and cannot link to siblings.Wrap your entire request handler:

export async function POST(req: Request) {
  const { userId, sessionId } = await getSession(req);

  return withZespanContext({ userId, sessionId }, async () => {
    const summary = await summarize(text);
    const response = await generate(summary);
    return Response.json({ response });
  });
}

withAgent not awaited

If you don’t await withAgent(...), the agent span may close before inner spans complete, breaking the parent-child link.

// ✓ Correct
await withAgent({ name: "MyAgent" }, async (agent) => { ... });

// ✗ Wrong — span closes immediately
withAgent({ name: "MyAgent" }, async (agent) => { ... });

Events missing in serverless (Lambda / Vercel / Cloud Run)

See the complete Serverless deployment guide for environment-specific patterns. Quick fix: call flush() before your handler returns.

# Python Lambda
def handler(event, context):
    result = call_llm(event["prompt"])
    zespan.get_client().flush()  # must be last line before return
    return {"body": result}

// TypeScript Lambda / Vercel
export default async function handler(req, res) {
  const result = await callLLM(req.body.prompt);
  await zespan.getClient().flush(); // must await before responding
  res.json({ result });
}

`401 Unauthorized` from the ingest endpoint

Cause: One of the following:

The API key was revoked or rotated and the old key is still in use
The x-api-key header is missing from the request
The key belongs to a different project

Go to Settings → API Keys, check that the key prefix matches the one your application is using, and rotate if necessary.

Rate limit `429` with “Monthly quota exceeded”

This is not a per-minute rate limit — it means your organization has exhausted its monthly event quota. Retrying later in the same month will not succeed. Options:

Upgrade your plan from Settings → Billing
Reduce your SDK sampleRate to send fewer events: zespan.init({ sampleRate: 0.5 })
Wait for your quota to reset at the start of next month

Prompt text not showing in trace detail

Cause: Prompt storage is on by default but may have been disabled. Verify storePrompts is not set to false in your init() call — PII redaction is applied to all stored text before transmission:

zespan.init({
  apiKey: "zsp_...",
  storePrompts: true, // default — set false to disable
});

Review your data retention policy before enabling this. Once stored, prompt text is subject to your plan’s retention window.

Python SDK not capturing async OpenAI calls

zespan.patch_openai() patches both sync and async clients. If async calls are still not traced, verify:

patch_openai() is called before any openai module is imported in your actual call path
You are using openai.AsyncOpenAI() (not a pre-initialized client from before the patch)

import zespan
zespan.init(api_key="zsp_...")
zespan.patch_openai()

# Create client AFTER patching
import openai
client = openai.AsyncOpenAI()  # ✓ this is patched

Still stuck?

Enable debug: true in your SDK init and share the console output. Open an issue on GitHub or email support@zespan.com.

​Traces not appearing in the dashboard

​Cost showing $0.00 for all events

​Parent-child spans not linking (broken trace tree)

​Events missing in serverless (Lambda / Vercel / Cloud Run)

​401 Unauthorized from the ingest endpoint

​Rate limit 429 with “Monthly quota exceeded”

​Prompt text not showing in trace detail

​Python SDK not capturing async OpenAI calls

​Still stuck?