> ## 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 atlanai CLI; `atlanai --map json` prints its command map. 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.

# Install and setup errors

> Errors from installing atlanai SDK, importing tracing, and configuring management and tracing credentials.

Start by printing the installed versions as described in [Install atlanai SDK](/tools/sdk/how-tos/install#verify-installation). A package that does not resolve explains most import errors before you look at credentials.

## `No matching distribution found for atlanai` from pip

pip stops with `ERROR: Could not find a version that satisfies the requirement atlanai (from versions: none)`. Above it, pip may list `Ignored the following versions that require a different python version` followed by the `atlanai` versions it skipped.

### Cause

The SDK requires Python 3.10 or later (`Requires-Python >=3.10`). On an older interpreter, pip ignores every release because none declares support for it, so it finds no candidate.

### Solution

Install with a supported interpreter.

1. Run `python --version` and confirm it prints 3.10 or later.
2. If it does not, create a virtual environment with a newer Python, for example `python3.12 -m venv .venv`, and activate it.
3. Run `pip install atlanai` again.
4. Run `python -c "import atlanai; print(atlanai.__version__)"` to confirm the package imports.

***

## `ModuleNotFoundError: atlanai.tracing needs the tracing extra`

Importing `atlanai.tracing` fails and the message names the tracing extra.

### Cause

Tracing's OpenTelemetry packages are an optional extra in Python. A plain `pip install atlanai` includes the `atlanai.tracing` module but not the packages it needs.

### Solution

Install the extra.

1. Run `pip install 'atlanai[tracing]'`.
2. Run `python -c "import atlanai.tracing as t; print(t.__version__)"`.
3. Confirm the version matches `atlanai.__version__`. If the two differ, run `pip install --upgrade 'atlanai[tracing]'` to align them.

***

## `init()` disables tracing and no traces are exported

The call returns, your application runs, and nothing reaches Agent Registry.

### Cause

`init()` turns tracing off, and logs a warning that starts with "tracing disabled", in these cases:

* There is no `ATLAN_API_KEY` and no `OTEL_EXPORTER_OTLP_*_ENDPOINT` setting.
* The service name is missing: `service_name` in Python, `serviceName` in TypeScript.
* `ATLAN_BASE_URL` is not `https`. Plain `http` is allowed only for loopback hosts such as `localhost`.

Setting `ATLAN_TRACING=false` also disables tracing, and it logs no warning.

### Solution

Match the warning to its setting.

1. Read the warning text. It names the missing setting.
2. Set `ATLAN_API_KEY` and `ATLAN_WORKSPACE_ID` in the environment of the process that calls `init()`. Tracing reads the process environment when `init()` runs, so a variable exported in a different terminal is not visible. In runtimes with no environment, such as Cloudflare Workers, pass `apiKey` and `workspaceId` to `init()` instead.
3. Pass a service name to `init()`.
4. Confirm `ATLAN_BASE_URL` is unset or starts with `https://`, and that `ATLAN_TRACING` is not `false`.
5. Run your code again and confirm the warning no longer appears.

***

## `AtlanConfigError: a workspace is required when exporting to an Atlan endpoint`

`init()` raises instead of returning a client.

### Cause

You configured an Atlan API key but no workspace. Traces sent without a workspace would land in the `default` workspace and be effectively lost, so the SDK refuses to start.

### Solution

Provide the workspace.

1. Set `ATLAN_WORKSPACE_ID` to the ID of the workspace that owns the traces.
2. Or pass `workspace_id` (Python) or `workspaceId` (TypeScript) to `init()`.
3. Run `init()` again and confirm it returns without raising.

***

## `AtlanAPIError` from management call

A call such as `client.auth.whoami()` raises `AtlanAPIError`.

### Cause

The Gateway returned a non-2xx response, or no response arrived. The error carries `status` and `code`, and `trace_id` (Python) or `traceId` (TypeScript) when the Gateway includes one. A `status` of `0` means the request failed before any response, for example because of a wrong Gateway URL or a network error.

### Solution

Read the error before you retry.

1. Print `error.status` and `error.code`.
2. If `status` is `0`, check that the Gateway URL is correct and reachable from your machine.
3. If `status` is not `0`, look up the `code` in [Errors and retries](/platform/references/errors-and-retries) and follow the cause listed there.
4. Keep the `trace_id` or `traceId` if you contact support.
5. Run the call again and confirm it returns your account.

## See also

* [Install atlanai SDK](/tools/sdk/how-tos/install): Install the SDK and confirm the package resolves.
* [Trace your first agent run](/tools/sdk/tutorials/quickstart): Initialize the tracing client and send your first trace.
* [Configuration reference](/tools/sdk/references/configuration): Every option and environment variable for management and tracing.
* [Errors and retries](/platform/references/errors-and-retries): Gateway error codes, causes, and when to retry.

## 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.