Trace errors

These are errors from sending traces with the SDK or an OTLP exporter and from importing traces from another store. Start from the symptom you see: each section below starts from one of them.

​

Traces appear under person instead of agent

An agent’s runs show up under a person, and the agent’s Sessions and Usage stay empty.

​

Cause

A trace belongs to the identity whose API key sent it. The runs were sent with a personal key. Setting the service name or ATLAN_AGENT_ID does not change this.

​

Solution

1. Open the agent’s Identity tab and select Rotate API key to get a key you can copy. The key is shown only once.
2. Store it in an approved secret store and set it as ATLAN_API_KEY for the agent’s runtime.
3. Send a new run and confirm it appears under the agent. Runs already sent stay where they landed.

---

​

Traces land in wrong workspace

Traces are readable, but not in the workspace you expected.

​

Cause

The workspace comes from the X-Atlan-Workspace-Id header, which the SDK sets from ATLAN_WORKSPACE_ID. Without it, traces land in the account’s default workspace.

​

Solution

1. Set ATLAN_WORKSPACE_ID, or send X-Atlan-Workspace-Id from your exporter.
2. Confirm the sending identity can write to that workspace.
3. Send a new run and read it back from the intended workspace.

---

​

SDK flush() fails

flush() raises or rejects before the process exits.

​

Cause

The exporter reported a delivery error, such as a refused key, an unreachable endpoint, or a rejected batch.

​

Solution

1. Inspect export_health (Python) or exportHealth (TypeScript) for the status, failure count, and error category.
2. Fix the cause it names, such as the API key or base URL.
3. Run again, and do not mark the run or an evaluation complete after a failed flush.

---

​

Import outcome unknown

An OTLP import timed out or returned 5xx, and you do not know whether the batch landed.

​

Cause

Delivery is unknown: the batch may have been accepted before the error.

​

Solution

1. Read back the traces the batch carried before you do anything else.
2. If they are missing, retry the unchanged batch with the same X-Atlan-Ingest-Id.
3. Never send a changed batch while the outcome is unknown.

---

​

Import returns 409

An OTLP batch is refused with 409.

​

Cause

The X-Atlan-Ingest-Id was reused with different facts, such as a changed payload, workspace, or creator.

​

Solution

1. Read back the traces the earlier batch carried.
2. Use a new ingest ID only for a deliberately changed payload.

---

​

Import returns 400, 401, 403, 413, or 422

An OTLP batch is refused before it is accepted.

​

Cause

• 400 or 422: The OTLP envelope, an identifier conversion, or a field is invalid.
• 401 or 403: The identity cannot write to the target workspace.
• 413: The batch is too large.

​

Solution

1. For 400 or 422, correct the envelope or field, then send a new batch.
2. For 401 or 403, confirm the sending identity and its workspace access. Do not change the workspace header to get around an access boundary.
3. For 413, split the batch between complete trace trees and remove optional fields your policy does not require.

---

​

Imported span tree flat or broken

An imported trace is readable, but its spans are not nested as in the source.

​

Cause

Span IDs or parent IDs were converted inconsistently, so children no longer point at their parents.

​

Solution

1. Use one deterministic conversion for every span ID and its parent ID.
2. Attach spans without a parent to the root span.
3. Re-import with a new ingest ID and compare the tree with the source.

---

​

Imported trace not found

The import returned 200, but the trace cannot be read back.

​

Cause

The batch is still processing, the read uses the wrong user ID or workspace, or the source trace ID was not kept.

​

Solution

1. Read with GET /registry/v1/users/{user_id}/traces/{trace_id}, using the user ID of the identity that sent the batch from GET /registry/v1/users/me.
2. Confirm the target workspace and that the source trace ID was kept or recorded.
3. Retry the read within a bounded deadline before importing again.

---

​

See also

• Send and verify traces: Send as the right identity and confirm delivery.
• Import traces from external stores: The import workflow these errors come from.

​

Need help

If you need assistance after trying these steps, contact Atlan support.