> 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

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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.