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

# Troubleshooting

> Debug missing runs, stuck runs, attribution, and local API issues.

## No runs appear

Check these first:

* `MARGOVIA_API_KEY` is set in the backend process that calls the model provider
* The SDK runs in backend code, not browser code
* The API key belongs to the Margovia project you are viewing
* Your provider call actually executes through the tracked client, wrapper, or provider helper
* `MARGOVIA_BASE_URL` is not accidentally pointing at localhost in production

Enable debug logs temporarily:

```env theme={null}
MARGOVIA_DEBUG=1
```

Without `MARGOVIA_API_KEY`, the SDK skips Margovia tracking and does not send events.

## Runs stay running

Tracked clients, wrapped provider calls, provider helpers, and `margovia.track(...)` complete or fail runs automatically.

Manual runs do not. If you call `startRun(...)`, you must eventually call one of:

```ts theme={null}
await run.complete({ outcome: "reply_generated" });
await run.fail({ error: "Provider timed out" });
```

Cost events alone do not close a manual run. This is intentional because a workflow can have several provider calls or tool calls before it is done.

## Runs appear but cost is zero

This usually means a run was created without a cost event.

Common causes:

* You used `margovia.track(...)` around a raw OpenAI or Anthropic client
* You called `startRun(...)` and `complete(...)` but never called `run.trackCost(...)`
* The provider response did not include usage fields

For a first integration, avoid this whole class of issue by using `margovia.openai(client)` or `margovia.anthropic(client)`.

Bad:

```ts theme={null}
await margovia.track({
  name: "score_tweet",
  fn: () => anthropic.messages.create(params)
});
```

If `anthropic` is not wrapped, Margovia cannot read token usage.

Fix with the tracked client:

```ts theme={null}
const anthropic = margovia.anthropic(new Anthropic());

await anthropic.messages.create({
  name: "score_tweet",
  customerId: "workspace_123",
  request: params
});
```

Or fix with a provider helper:

```ts theme={null}
await margovia.trackAnthropic({
  name: "score_tweet",
  request: params,
  fn: () => anthropic.messages.create(params)
});
```

Or fix with a wrapped client:

```ts theme={null}
const anthropic = margovia.wrapAnthropic(new Anthropic());

await margovia.track({
  name: "score_tweet",
  fn: () => anthropic.messages.create(params)
});
```

## Customer margin is missing

Margin requires both cost and revenue context.

Send customer attribution:

```ts theme={null}
{
  customerId: `workspace_${workspace.id}`,
  customerName: workspace.name,
  customerPlan: { name: "pro", monthlyUsd: 99 }
}
```

If only `customerId` is sent, Margovia can group usage but cannot calculate margin until plan revenue is available.

## Customer IDs look wrong

Margovia stores `customerId` exactly as sent by your app.

If you send `"1"`, the dashboard will show and group by `"1"`. Prefer namespaced IDs:

```ts theme={null}
customerId: `workspace_${workspace.id}`
customerId: `org_${organization.id}`
customerId: `stripe_${stripeCustomer.id}`
```

Use `customerName` or dashboard aliases for display names. Do not change `customerId` just to make the UI prettier.

## Costs look too low or too high

Check:

* The provider response includes usage fields
* The model name matches Margovia pricing
* Cached input and reasoning token fields are being reported by the provider
* Manual `costUsd` values are in USD, not cents

For custom providers, send `costUsd` explicitly:

```ts theme={null}
await run.trackCost({
  provider: "custom",
  label: "reranker",
  costUsd: 0.0042,
  status: "success"
});
```

## Local development hits the wrong API

With `MARGOVIA_API_KEY` configured and no `MARGOVIA_BASE_URL`, the SDK sends to Margovia Cloud by default.

For a local API:

```env theme={null}
MARGOVIA_BASE_URL=http://localhost:4010
```

Remove `MARGOVIA_BASE_URL` in production unless you intentionally use a custom API host.