Skip to main content
Start by printing the installed versions as described in Install atlanai SDK. 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 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

​
Need help

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