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.- Run
python --versionand confirm it prints 3.10 or later. - If it does not, create a virtual environment with a newer Python, for example
python3.12 -m venv .venv, and activate it. - Run
pip install atlanaiagain. - 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 plainpip install atlanai includes the atlanai.tracing module but not the packages it needs.
Solution
Install the extra.- Run
pip install 'atlanai[tracing]'. - Run
python -c "import atlanai.tracing as t; print(t.__version__)". - Confirm the version matches
atlanai.__version__. If the two differ, runpip install --upgrade 'atlanai[tracing]'to align them.
init() disables tracing and no traces are exported
The call returns, your application runs, and nothing reaches Atlan Trident.
Cause
init() turns tracing off, and logs a warning that starts with “tracing disabled”, in these cases:
- There is no
ATLAN_API_KEYand noOTEL_EXPORTER_OTLP_*_ENDPOINTsetting. - The service name is missing:
service_namein Python,serviceNamein TypeScript. ATLAN_BASE_URLis nothttps. Plainhttpis allowed only for loopback hosts such aslocalhost.
ATLAN_TRACING=false also disables tracing, and it logs no warning.
Solution
Match the warning to its setting.- Read the warning text. It names the missing setting.
- Set
ATLAN_API_KEYandATLAN_WORKSPACE_IDin the environment of the process that callsinit(). Tracing reads the process environment wheninit()runs, so a variable exported in a different terminal is not visible. In runtimes with no environment, such as Cloudflare Workers, passapiKeyandworkspaceIdtoinit()instead. - Pass a service name to
init(). - Confirm
ATLAN_BASE_URLis unset or starts withhttps://, and thatATLAN_TRACINGis notfalse. - 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 thedefault workspace and be effectively lost, so the SDK refuses to start.
Solution
Provide the workspace.- Set
ATLAN_WORKSPACE_IDto the ID of the workspace that owns the traces. - Or pass
workspace_id(Python) orworkspaceId(TypeScript) toinit(). - 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 carriesstatus 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.- Print
error.statusanderror.code. - If
statusis0, check that the Gateway URL is correct and reachable from your machine. - If
statusis not0, look up thecodein Errors and retries and follow the cause listed there. - Keep the
trace_idortraceIdif you contact support. - Run the call again and confirm it returns your account.
No instrumentation startup line in debug output
Running withATLAN_DEBUG=true, the expected line such as atlanai: openai instrumentation on does not appear.
Cause
One of:init()was not passed the integration name. Theinstrumentoption (orATLAN_INSTRUMENTenvironment variable) must name it explicitly — nothing is traced unless you name it.- The integration’s package is not installed in the environment that runs
init(). Each integration activates only when its package is present:openaifor OpenAI SDK,anthropicfor Anthropic SDK,boto3orbotocorefor AWS Bedrock,claude-agent-sdkfor Claude Agent SDK. - For Claude Agent SDK in TypeScript: the app is calling the original
queryinstead of the one returned bywrapClaudeAgentSDK.
Solution
- Confirm
init()receives the name, for exampleinstrument=["openai"]in Python orinstrument: ["openai"]in TypeScript. - In the same environment that runs
init(), confirm the package is installed:pip show openai,pip show anthropic,pip show boto3, orpip show claude-agent-sdkin Python, ornpm ls openaiin TypeScript. - For Claude Agent SDK in TypeScript, confirm the app imports
queryfrom the objectwrapClaudeAgentSDKreturned, not from@anthropic-ai/claude-agent-sdkdirectly. - Run again with
ATLAN_DEBUG=trueand confirm the startup line appears.
A warning says openai could not be loaded synchronously
At startup in TypeScript, a warning reads openai instrumentation: unsupported runtime, openai could not be loaded synchronously, and calls that ran before openai was wrapped are not traced.
Cause
The SDK wraps theopenai package while init() runs, which needs a synchronous load of the package. A loader hook such as tsx, a top-level await in openai, or Node.js older than 20.19 or 22.12 forces a later, asynchronous load.
Solution
- Run compiled JavaScript on Node.js 20.19 or later in the 20 line, or 22.12 or later, with no loader hooks such as
tsx. - Confirm
openaiis not loaded behind a top-level await. - Run again and confirm the warning is gone. Calls that start after
openaiis wrapped are traced either way, as the warning says.
A version-outside-tested-range warning appears at startup
init() logs a warning that the installed version of an integration package is outside the tested range.
Cause
The integration was tested against a specific version range. The installed version is older or newer than that range. Tracing still runs.Solution
Tracing continues and spans are complete in most cases. If spans look incomplete or attributes are missing, upgrade the integration package to a version in the tested range and run again.See also
- Install atlanai SDK: Install the SDK and confirm the package resolves.
- Trace your first agent run: Initialize the tracing client and send your first trace.
- Configuration: Every option and environment variable for management and tracing.
- Errors and retries: Gateway error codes, causes, and when to retry.