> ## Documentation Index > Fetch the complete documentation index at: https://platform.atlan.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `brain` CLI; `brain --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write. > The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects. > SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript. > These docs cover Atlan Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces. # Trace errors > Symptoms, causes, and fixes for traces under the wrong identity or workspace, failed SDK delivery, and OTLP ingest and import 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](/registry/traces/how-tos/send-and-verify): Send as the right identity and confirm delivery. * [Import traces from external stores](/traces/how-tos/import-traces): The import workflow these errors come from. ## Need help If you need assistance after trying these steps, contact Atlan support. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.