> 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/2.-get-started/first-day-errors.md).

# First-day errors

First-day errors — the auth, install, and network problems most people hit on day 1, with fixes.

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](/more-in-this-section-9/organizations-1.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](/more-in-this-section-4/cicd.md).

## Still stuck

* [SDK troubleshooting](/more-in-this-section-9/troubleshooting.md)
* [Support — contact](/12.-support/contact.md)
* [Status and reliability](/13.5-operational/status.md)