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

# Fix Fractal SDK Issues: Traces, Vercel, and Init Order

> Resolve the most common reasons LLM traces aren't appearing in your Fractal dashboard, from Vercel runtime mismatches to initialization ordering.

## No traces at all — check your baseUrl host

Traces are exported to `{baseUrl}/api/v1/traces`. The ingest endpoint lives on `platform.belvedir.ai` (also served on `belvedir.ai` and the legacy `platform.fractalresearch.ai`). Pointing `baseUrl` at any other host returns a 404 and the spans are dropped silently — the SDK keeps running and your app shows no error, but nothing is ever stored. Safest is to omit `baseUrl` entirely, since it defaults to `https://platform.belvedir.ai`.

## No traces appearing on Vercel

The Belvedir SDK relies on OpenTelemetry, which requires the Node.js runtime. On Vercel, routes can default to the Edge runtime where the SDK silently skips initialization. Add the following to any API route that makes LLM calls:

```ts theme={null}
export const runtime = 'nodejs'
```

## I see HTTP spans but no anthropic.chat / openai.chat span

The patch didn't take — this happens when the LLM SDK was imported before `initialize()` ran. In Next.js, keep initialization in `instrumentation.ts` (not a route file) and restart `next dev`. If you see the `initialize() ran after ... was imported` warning on startup, that's the cause. In a plain Node process, call `initialize()` at the very top of your entry file, before importing OpenAI/Anthropic.

In Next.js there's a second cause: the bundler inlines the LLM SDK into the route, or loads it as an ES module — either way the `require()` hook auto-instrumentation relies on never fires, even with `serverExternalPackages` set. The reliable fix is to pass your LLM SDKs to `initialize()` via `instrumentModules` so they are patched directly, no matter how they were loaded:

```ts theme={null}
// instrumentation.ts
const openai = await import("openai");
const anthropic = await import("@anthropic-ai/sdk");
initialize({
  apiKey: process.env.FRACTAL_API_KEY,
  instrumentModules: { openAI: openai.OpenAI, anthropic },
});
```

Requires `@fractalresearch/loop@0.1.3` or later. **Also keep the LLM SDKs external** so every bundle shares one runtime copy — if they get inlined, each bundle has its own private copy and `instrumentModules` patches one your routes never use. Mind the version-specific config key: on Next 15+ it's top-level `serverExternalPackages`; on Next 13/14 it's `experimental.serverComponentsExternalPackages` — the Next 15 name is silently ignored there (the build prints an `Unrecognized key(s)` warning; don't ignore it).

## Traces show up but no tasks or groups

Tasks and groups only form for work wrapped in `withSession`. Make sure your agent runs inside it, and give the session \~30s of inactivity — segmentation only runs once a session goes quiet.

## Traces missing in development

Ensure your `FRACTAL_API_KEY` environment variable is set and that `initialize()` is called before any LLM client is created. Check your terminal for SDK warnings on startup.