# First-day errors

Most new users hit one of these in their first hour. Find your symptom, apply the fix.

## "command not found: layerlens" after pip install

**Cause:** the `layerlens` CLI installed but isn't on your PATH.

**Fix:**

* On macOS/Linux: confirm `~/.local/bin` (or your venv `bin/`) is on PATH
* In a venv: activate it (`source.venv/bin/activate`)
* Reinstall in the active venv: `pip install layerlens --extra-index-url https://sdk.layerlens.ai/package`

## `pip install` returns "Could not find a version"

**Cause:** missing the `--extra-index-url` flag.

**Fix:** always use the LayerLens package index:

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

## `AuthenticationError: invalid API key`

**Cause:** wrong key, wrong env-var name, or expired key.

**Fix:**

1. Verify env var name is `LAYERLENS_STRATIX_API_KEY` (not `LAYERLENS_API_KEY`)
2. Echo it: `echo $LAYERLENS_STRATIX_API_KEY` — should show your key (or its prefix)
3. Generate a fresh key in **Settings → API keys**
4. If using a CI runner, check the secret name matches

## `ConnectionError` / `httpx.ConnectError` to `stratix.layerlens.ai`

**Cause:** firewall, proxy, or DNS.

**Fix:**

1. Confirm DNS: `nslookup stratix.layerlens.ai` should resolve
2. Confirm reachability: `curl -I https://stratix.layerlens.ai/health`
3. If behind a corporate proxy: set `HTTPS_PROXY` env var; ensure CA bundle is configured
4. If using `--extra-index-url`, confirm `sdk.layerlens.ai` is also reachable

## `ImportError: cannot import name 'Stratix' from 'layerlens'`

**Cause:** old SDK version, or `layerlens` namespace collision.

**Fix:**

1. `pip show layerlens` — verify version ≥ 1.3.0
2. Upgrade: `pip install --upgrade layerlens --extra-index-url https://sdk.layerlens.ai/package`
3. If still failing, check for a local file or directory named `layerlens.py` shadowing the install

## `RateLimitError` on first 5 calls

**Cause:** rare on day 1; usually concurrent retries from a flaky network.

**Fix:** the SDK retries with backoff automatically. If it persists, drop concurrency and confirm your API key isn't shared across multiple processes.

## "I don't see my evaluation in the UI"

**Cause:** wrong active org.

**Fix:** the API key is scoped to one org; the dashboard's active org may differ. Switch active org in the top bar to match the key's org. See [Organizations](https://github.com/LayerLens/gitbook-full/blob/main/13-reference/sdk-python/organizations.md).

## CI: `LAYERLENS_STRATIX_API_KEY` not set

**Cause:** secret not configured on the runner.

**Fix (GitHub Actions):**

```yaml
env:
 LAYERLENS_STRATIX_API_KEY: ${{ secrets.LAYERLENS_STRATIX_API_KEY }}
```

For other CIs, see [CI/CD integrations](https://github.com/LayerLens/gitbook-full/blob/main/06-build/integrations/cicd.md).

## Still stuck

* [SDK troubleshooting](https://github.com/LayerLens/gitbook-full/blob/main/13-reference/sdk-python/troubleshooting.md)
* [Support — contact](/12.-support/contact.md)
* [Status page](https://status.layerlens.ai)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.layerlens.ai/2.-get-started/first-day-errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.