> ## Documentation Index
> Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting traces

> Why your AgentMark traces aren't showing up, the silent failures that drop spans, and how to fix each one.

Most "tracing isn't working" reports are one of a handful of **silent failures**: the app runs fine and throws no error, but spans never arrive. Find your symptom below.

<Note>
  Hitting an error with an explicit message (model not registered, 401, command not found) instead? See the general [Troubleshooting](/reference/troubleshooting) reference.
</Note>

## No traces appear at all

The SDK ran, but nothing reached AgentMark.

### The env vars weren't loaded when the app ran

`AGENTMARK_API_KEY` / `AGENTMARK_APP_ID` decide where traces go, and **Node doesn't load `.env` by itself**. If the process started without them, the SDK has nowhere to send to.

```bash theme={null}
# Load .env explicitly
node --env-file=.env src/agent.ts   # --env-file: Node 20.6+; running .ts directly: Node 22.18+
# or: set -a; . ./.env; set +a; npm run agent
```

Confirm the values are present at construction time (`console.log(!!process.env.AGENTMARK_API_KEY)` right before `new AgentMarkSDK(...)`). In local development, `agentmark dev` receives traces at `http://localhost:9418` automatically, no key needed.

### A short-lived script exited before spans flushed

The SDK batches spans, so a CLI, serverless handler, or cron job can exit before the SDK sends the batch. Disable batching and flush on the way out:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const tracer = sdk.initTracing({ registerGlobally: true, disableBatch: true });
    // ... your work ...
    await tracer.forceFlush();
    await tracer.shutdown();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    tracer = sdk.init_tracing(disable_batch=True)
    # ... your work ...
    tracer.shutdown()
    ```
  </Tab>
</Tabs>

## Traces appear, but the model span is missing

You see your custom spans (`span()`, `observe()`), but the generation span (model name, token usage, input/output) is absent. Two causes, often together.

### `registerGlobally: true` is missing

The AI SDK emits the model span through the **global** OpenTelemetry tracer. AgentMark's tracer stays isolated by default so it never clobbers an existing OTel setup in your app. Without `registerGlobally: true`, the model span goes to a no-op tracer and silently vanishes while your custom spans keep working.

```typescript theme={null}
const tracer = sdk.initTracing({ registerGlobally: true });
```

Pass it unless your app already registers its own global OTel provider.

### (Vercel AI SDK) telemetry isn't enabled on the call

Every `generateText` / `streamText` / `generateObject` call must opt in, or it emits no spans:

```typescript theme={null}
const { text } = await generateText({
  model: openai("gpt-4o-mini"),
  prompt,
  experimental_telemetry: { isEnabled: true },
});
```

When you render through AgentMark, the render is neutral (`format()` returns `{ messages, text_config }` and doesn't enable telemetry for you), so enable telemetry on the model call itself:

```typescript theme={null}
const { messages, text_config } = await prompt.format({
  props: { name: "Alice" },
});
const { text } = await generateText({
  model: openai(text_config.model_name.replace(/^openai\//, "")),
  messages,
  experimental_telemetry: { isEnabled: true },
});
```

## Quick checklist

* **Nothing at all?** → env vars loaded when the process started; for scripts, `disableBatch: true` + `await tracer.shutdown()`.
* **Custom spans but no model span?** → `registerGlobally: true`, and (Vercel AI SDK) `experimental_telemetry: { isEnabled: true }` on every call.
* **Local dev?** → traces go to `http://localhost:9418`; make sure `agentmark dev` is running.

## Still stuck?

For errors with an explicit message (model not registered, 401, MCP server not found, …), see the [error reference](/reference/troubleshooting). Otherwise open an issue on [GitHub](https://github.com/agentmark-ai/agentmark/issues) with your SDK versions and a minimal reproduction.

<div className="mt-8 rounded-lg bg-blue-50 p-6 dark:bg-blue-900/30">
  <h3 className="font-semibold mb-3">Have questions?</h3>
  <p className="mb-4">Reach out any time:</p>

  <ul>
    <li>
      Email the team at <a href="mailto:hello@agentmark.co" className="text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-200">[hello@agentmark.co](mailto:hello@agentmark.co)</a> for support
    </li>

    <li>
      Schedule an <a href="https://cal.com/ryan-randall/enterprise" className="text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-200">Enterprise Demo</a> to learn about AgentMark's business solutions
    </li>
  </ul>
</div>