> For the complete documentation index, see [llms.txt](https://docs.layerlens.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layerlens.ai/more-in-this-section-9/troubleshooting.md).

# 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/`](https://github.com/layerlens/stratix-python/tree/main/docs/troubleshooting).

## Installation

### Package not found

```
Could not find a version that satisfies the requirement layerlens
```

Include the LayerLens index URL:

```bash
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:

```bash
export LAYERLENS_STRATIX_API_KEY="..."
```

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

### Invalid / expired API key

`AuthenticationError` (HTTP 401) or `NotFoundError` during init. Verify the key in the [LayerLens dashboard](https://stratix.layerlens.ai).

## Evaluations

### Stuck `wait_for_completion`

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

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

### Model or benchmark not found

`get_by_key` is case-sensitive:

```python
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:

```python
# 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:

```python
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](/more-in-this-section-9/errors-1.md) for the full exception hierarchy and HTTP-status mapping.

## See also

* [Errors](/more-in-this-section-9/errors-1.md)
* [Client configuration](/more-in-this-section-9/client.md) — timeout, retries, max\_retries
* [Support — first-day errors](/2.-get-started/first-day-errors.md)
* [Cookbook: rate-limit handling](/more-in-this-section-9/rate-limit-handling.md)