SDK troubleshooting

SDK troubleshooting — installation, authentication, evaluation, trace upload, timeouts.

Adapted from the SDK's own troubleshooting docs. For the canonical reference, see stratix-python/docs/troubleshooting/.

Installation

Package not found

Could not find a version that satisfies the requirement layerlens

Include the LayerLens index URL:

pip install layerlens --extra-index-url https://sdk.layerlens.ai/package

Python version

Requires Python 3.8+. Check: python --version.

Client initialization

Missing API key

StratixError: The api_key client option must be set either by passing api_key to the client
or by setting the LAYERLENS_STRATIX_API_KEY environment variable

Set the env var or pass explicitly:

export LAYERLENS_STRATIX_API_KEY="..."

client = Stratix(api_key="...")

Invalid / expired API key

AuthenticationError (HTTP 401) or NotFoundError during init. Verify the key in the LayerLens dashboard.

Evaluations

Stuck wait_for_completion

The evaluation may be queued behind other jobs. Check status:

evaluation = client.evaluations.get(evaluation.id)
print(f"Status: {evaluation.status}")

Model or benchmark not found

get_by_key is case-sensitive:

model = client.models.get_by_key("openai/gpt-4o") # correct
# Search by name if unsure
models = client.models.get(type="public", name="gpt-4o")

Trace uploads

File too large

Trace files must be under 50 MB. Split larger datasets.

Invalid file format

.json and .jsonl only. Validate JSON shape before upload.

Timeouts

Default timeout is 10 minutes (600s). Override:

# At client level
client = Stratix(timeout=1200.0)

# Per-request
result = client.with_options(timeout=300.0).evaluations.create(...)

Rate limits (429)

The SDK auto-retries with exponential backoff and respects Retry-After. To handle directly:

import layerlens
try:
 client.evaluations.create(...)
except layerlens.RateLimitError as e:
 print(f"Retry after: {e.response.headers.get('retry-after')}s")

Error code reference

See Errors for the full exception hierarchy and HTTP-status mapping.

See also

• Errors
• Client configuration — timeout, retries, max_retries
• Support — first-day errors
• Cookbook: rate-limit handling