Home / Support / Troubleshooting

Troubleshooting

If something broke, search this page first. Most errors fall into 8 buckets.

Install & setup

"uv: command not found"

You haven't installed uv yet. One-time:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then restart your terminal so the PATH update takes effect.

"uv sync" fails with "Failed to build <package>"

Usually a missing system library for a native Python dep.

Ubuntu/Debian: sudo apt install python3-dev build-essential libssl-dev libffi-dev
macOS: xcode-select --install
Windows: install Visual C++ Build Tools

Re-run uv sync.

"playwright install chromium" hangs forever

Network restriction. Set the download mirror:

export PLAYWRIGHT_DOWNLOAD_HOST=https://playwright.azureedge.net
playwright install chromium

"ANTHROPIC_API_KEY not found"

The operator reads secrets.env in the project root. Make sure you copied the example file:

cp secrets.env.example secrets.env

Then edit secrets.env and add your key. Don't quote the value — just ANTHROPIC_API_KEY=sk-ant-... on its own line.

RAG index

"orchestrator.rag build" downloads slowly

First run downloads the bge-small-en-v1.5 embedding model (~130 MB). After that, builds are instant. Speed depends on your connection — give it 2–5 min on first run.

"No results from rag.retrieve"

You forgot to build the index. Run python -m orchestrator.rag build once.

Browser issues

The Chrome window opens but the page is blank / "translate this page" loop

Most often a corrupted persistent profile. Nuke it:

rm -rf ./.browser_profile
# then re-launch

The first run after deletion is treated as a brand-new profile — log in manually once if needed, then subsequent runs reuse the fresh cookies.

"Element is not visible" / clicks miss

Usually a viewport size mismatch with the page's responsive layout. Open browser/playwright_human.py and adjust viewport=(1366, 768) to your actual screen. Or force the page to a known layout with session.scroll() before the click.

Captcha appears on a tool flow

Switch that tool to the MCP-Chrome adapter so Claude can see the captcha and solve it (image captchas) or pause for you (reCAPTCHA / hCaptcha). For Cloudflare Turnstile + similar, the only reliable path is a residential proxy + manual one-time solve, then the cookie is cached in the profile dir.

Facebook says "We've detected unusual activity" the second I log in

You're hitting Facebook's device-fingerprint check. Two fixes, in order:

Use the same browser profile every time (the persistent .browser_profile handles this — make sure it's not being deleted).
If still flagged: log in manually in your regular Chrome from the same network first, verify the device, then launch the operator profile from the same machine.

Tool errors

"clickbank_top_offers returned a stub note"

The Clickbank tool is intentionally a contract stub in the bundled download — the marketplace scrape needs your Clickbank login. Edit tools/networks/__init__.py and replace the stub with a real Playwright-driven marketplace scrape, or use Clickbank's API key.

"WP REST API returns 401"

WordPress doesn't accept admin password by default over REST. Install the Application Passwords feature (built into modern WP) and generate a dedicated password for the operator. Use that as WP_ADMIN_PASSWORD.

"Anthropic rate limit hit"

You're on a free tier or low-cap tier. Either:

Add credits at console.anthropic.com
Drop to a smaller model: set ANTHROPIC_MODEL=claude-haiku-4-5-20251001 in secrets.env
Add backoff: tenacity.retry is already imported, wrap the agent.create() call

Pixel & tracking

"Pixel Helper shows PageView but no ViewContent"

Your lander loaded the base pixel but the fbq('track','ViewContent') call didn't fire. Open browser DevTools → Console — look for a JS error. Common cause: the inline script ran before fbq was defined. Move the ViewContent call inside a DOMContentLoaded listener or to the end of the page.

"Sale showed up in Clickbank but no Purchase event in FB"

Your postback isn't wired. See Module 06 — Conversions. Either configure vendor pixel forwarding (easy) or stand up a CAPI bridge webhook (harder).

Performance

"Agent runs are slow / spending too many tokens"

Three optimizations in order of impact:

Verify prompt caching is working: in your usage dashboard, you should see "cache read" tokens after step 1 of each run. If not, the system prompt is changing between calls.
Drop to Haiku for routine read-only tool selection: set ANTHROPIC_FAST_MODEL and use it for the critic pass.
Reduce RAG top-k from 8 to 5 in rag.retrieve() calls if your runs frequently include irrelevant chunks.

"Browser session leaks memory after long runs"

Playwright's context can leak with very long sessions. The runners auto-restart the browser every 30 min. For custom scripts, call session.close() + re-open() periodically.

When all else fails

Check ./logs/<run-id>.jsonl — full tool input/output log.
Check ./screenshots/<timestamp>.png — captured at every navigation.
Run the failing tool by itself in a Python REPL to isolate.
Contact me with the log excerpt + the screenshot. Include your OS, Python version, and the exact command you ran.