Troubleshooting & FAQ
Answers for the most common Cartographer support questions. For error code reference, see Error codes. Contact support@molar.it for account-specific issues.
Quick diagnostics
Run these checks first:
| Check | How |
|---|---|
| API health | GET /healthz or dashboard health strip |
| Workers registered | Hatchet UI (:8080 local) or health strip "Agent worker" |
| LLM configured | Settings → AI & models — all required capabilities green |
| Quota headroom | Billing → Usage → Plan limits |
| Live stream | Run detail — WebSocket connected (no reconnect banner) |
Local all-in-one:
make verify-phase-0
FAQ
What is Cartographer?
An autonomous QA agent that crawls your app, verifies user flows in a real browser, and exports Playwright tests. See Overview.
Do I need Playwright experience?
Helpful but not required. Export produces runnable tests; your team edits assertions like any other suite.
Can Cartographer test production?
Yes, with caution. Use read-only goals first, respect rate limits, and prefer staging. Production runs appear in audit logs.
Does exported code need CloakBrowser?
No by default. Exported playwright.config.ts uses stock Chromium. Opt in only if your CI targets bot-protected sites.
Which LLM providers are required?
None specific on Molar Cloud hosted models. Self-hosters need at least one text model (planner) and one vision model (tier-1 escalation) unless tier 0-only + local tier 2.
How is my data isolated?
Every query is scoped by org_id. Artifacts live under org/project prefixes in object storage. See security docs for RLS and vault details.
Can I use Cartographer without the dashboard?
Yes — cartog mcp (stdio) and cartog ci expose the REST API from your IDE or shell. The dashboard adds route maps, live run streaming, and the /traces viewer.
What is the difference between a crawl and a run?
Crawl discovers URLs (route map). Run pursues a goal with verification (trajectory). See Core concepts.
Authentication & login
| Symptom | Cause | Fix |
|---|---|---|
| Redirect loop on login | BETTER_AUTH_URL mismatch | Standalone: match web origin; combined: point to app.molar.it |
| API 401 from dashboard | dashboard API JWT or session expired | Re-login; check BFF_JWT_SECRET consistent across web/API |
| MCP OAuth fails | Wrong resource URL | Use https://mcp.molar.cloud as RFC 8707 resource |
CLI whoami fails | Invalid or expired PAT | cartog config set token <new-pat> |
Note:
Do not store session tokens in localStorage. Cartographer uses HttpOnly cookies for browser sessions.
System health / blocked actions
| Health check red | Fix |
|---|---|
API /healthz | Start API container / check CARTOGRAPHER_API_URL |
ANTHROPIC_API_KEY / planner | Add key or enable Molar-hosted routing |
GOOGLE_API_KEY | Required for tier-1 and export healer unless fully tier-0 + BYOK alternate |
| Hatchet unreachable | Start Hatchet stack; verify HATCHET_CLIENT_TOKEN |
| Agent worker missing | make agent-worker or scale worker deployment |
| Crawl worker missing | make crawl-worker |
| Export worker missing | make export-worker |
| Redis unreachable | Start Redis; live stream won't work |
| MinIO/S3 unreachable | Artifacts and screenshots fail — fix S3_* vars |
Crawls
| Symptom | Likely cause | Fix |
|---|---|---|
| Crawl stuck at 0 pages | Seed URL unreachable or blocked | Verify URL in browser; enable anti-bot |
| Very few pages on SPA | Link-only phase insufficient | Enable interactive crawl for deeper discovery |
| Crawl killed mid-flight | Worker crash or OOM | Resume from checkpoint; lower max_pages |
| 429 on crawl start | Daily page quota | Wait for reset or upgrade plan |
| robots.txt blocked | Policy respected | Override in project settings only if you own the site |
Agent runs
| Symptom | Likely cause | Fix |
|---|---|---|
| Run queued forever | No agent worker | Register worker in Hatchet |
| Max steps exceeded | Goal too long or loop | Increase max_steps; narrow goal |
| Tier 1 spam / high cost | Canvas-heavy UI | Expected; set vlm_budget_cents; improve data-testid on app |
| Login fails | Missing credentials | Create credential alias; pass credentials_alias |
| Wrong page after click | Ambiguous DOM | Raise grounding tier to 1; fix aria labels in app |
| HITL pause | Low confidence / sensitive action | Approve in extension queue or dashboard |
| Run succeeded but wrong outcome | Weak assertions | Edit goal to include explicit verify clause |
Self-heal exhausted
The actor retries alternate selectors before failing. If all tiers fail:
- Open Trace at failure step
- Use Debugger chat to understand DOM state
- Re-run with
record_demoafter manual path - Add
data-testidto unstable elements (export will prefer them)
Export
| Symptom | Likely cause | Fix |
|---|---|---|
| Export button disabled | Run not succeeded | Fix run or export with include_failed_branches if supported |
| Healer loop failed | Site changed during export | Re-run agent; export again |
| Lint errors in zip | Generated anti-patterns | Report issue — healer should fix; manual edit |
| Self-verify timeout | Sandbox cannot reach app | Allow egress to staging URL from worker network |
| Low testid warning | App lacks stable ids | Add data-testid — warning is advisory |
MCP & IDE
| Symptom | Fix |
|---|---|
cartog mcp silent hang | Ensure stderr only in MCP mode; check API URL |
| Tool timeout | Increase client timeout; long runs use task polling |
| 401 on HTTP MCP | Complete OAuth; check token audience |
| Progress stops | Call cartographer_get_task; verify MCP_HTTP_BASE_URL points at API (:8000 locally) |
| Wrong project | Pass explicit project_id |
Browser extension
| Symptom | Fix |
|---|---|
| Disconnected | Re-login; cartog browser connect |
| Relay 403 | Add origin to project allowlist |
| Recording empty | Navigate slowly; wait for soft chunk boundaries |
| Approval not shown | Confirm extension adapter selected |
See Browser extension.
Docker / local dev
| Symptom | Fix |
|---|---|
make bootstrap slow | Normal first time (~30 min, CloakBrowser download) |
| Docker OOM | Allocate ≥6 GB RAM to Docker Desktop |
| CloakBrowser checksum fail | Never set CLOAKBROWSER_SKIP_CHECKSUM=true — re-download |
| Port conflicts | Stop other services on 3000/8000/5432 or remap compose |
| macOS worker wedge | Restart workers after sleep; see repo gotchas doc |
Quotas and billing errors
| HTTP | Meaning | Action |
|---|---|---|
| 429 | Daily run or crawl page quota | Billing → Usage; upgrade or wait UTC day rollover |
| 402 | Hosted LLM spend cap | Add BYOK or raise cap (Owner) |
| 403 | Missing Cartographer entitlement | Upgrade SKU or contact sales |
Performance
| Question | Guidance |
|---|---|
| Crawl slow on large site | Lower depth; scope allowlist to subdomain |
| Run slow | Tier 0 is fastest; tier 1 adds ~500ms per escalation |
| Export slow | Healer + self-verify add minutes — normal for large trajectories |
| Many parallel runs | Plan limits concurrency; queue in Hatchet |
Getting help
- Copy the run ID, trace link, and timestamp
- Note deployment mode (cloud / self-hosted) and plan tier
- Email support@molar.it or use in-app Help
- For security issues: security@molar.it (do not post secrets in tickets)
Include: goal text, base_url, grounding tier, browser adapter, and whether extension was connected — never include credential values.