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:

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.

CI: LAYERLENS_STRATIX_API_KEY not set

Cause: secret not configured on the runner.

Fix (GitHub Actions):

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

For other CIs, see CI/CD integrations.

Still stuck

• SDK troubleshooting
• Support — contact
• Status and reliability