Troubleshooting¶
What you'll do: fix common install, connection, and extraction problems.
Install and host¶
| Symptom | Cause | Fix |
|---|---|---|
release manifest ... mismatch |
Manifest version, RID, tarball name, or SHA field does not match the requested release | Stop. Download the matching archive + manifest pair from the same release; do not bypass the check |
verified release archive is incomplete |
The archive lacks its platform host, matching VERSION / inner manifest, or a required runtime helper |
Stop. Re-download the official release assets or repair the mirror; the existing install is not replaced |
Refusing to replace OCCAM_INSTALL_DIR |
The target is a source checkout, link/reparse point, malformed release, wrong-RID release, or unrelated directory | Correct OCCAM_INSTALL_DIR; do not delete the target blindly. The installer stopped before process preparation or moving files |
refusing to overwrite unrelated launcher |
~/.local/bin already contains an occam launcher that was not generated by Occam |
Rename the unrelated command or choose which program should own that name, then rerun. Occam leaves every existing launcher unchanged |
workers_unavailable |
OCCAM_HOME unset or workers missing |
Set OCCAM_HOME to repo root; run .\scripts\occam-doctor.ps1 |
occam is not recognized after npm install -g ff-occam |
npm does not install the operator CLI; on Windows the npm global bin is often missing from PATH | Do not run occam connect from npm. Use the bootstrap in Install. MCP-only trial: npx ff-occam@1.1.1 |
occam connect / doctor via npx ff-occam |
npm package only starts the MCP host | Use guarded install (get-ff-occam), then occam connect — see Install |
AOT host: GLIBC_2.38 not found (Linux containers) |
Published linux-x64 binary needs glibc ≥ 2.38 (e.g. Ubuntu 24.04+); Debian bookworm is too old | Use Ubuntu 24.04+ / newer glibc, or run from a host matching the release RID |
| MCP server exits immediately | Crash on startup | Run host manually; read stderr |
| Zero tools in client | Host failed to register | Reload MCP after doctor; check Node 20+ |
playwright_missing in message / browser failure.fix present |
Chromium not installed | Run the failure.fix.command — occam install-browser (user-level, no root). Or cd workers/browser-extract && npx playwright install chromium |
Browser worker no_json |
OOM or crash | Reload MCP; try OCCAM_BROWSER_NODE_MAX_OLD_SPACE_MB=512 |
dns_error on every external URL (but the host resolves fine) |
Node < 20 — the worker's undici needs the File global (Node 20+); it fails to load and the fetch path reports a misleading dns_error |
Run occam on Node 20+. occam-wrapper.sh auto-prefers a newer node from ~/.local/node20/bin, /opt/node20/bin, or /usr/local/bin if the default is older |
Extraction¶
| Symptom | Cause | Fix |
|---|---|---|
| Empty or tiny markdown | SPA or thin HTTP extract | backend_policy=browser or http_then_browser |
captcha_or_challenge |
Cloudflare / bot wall | Stop; export session cookies only if site allows |
requires_login / http_403 |
Gated content | occam-session.mjs export-state → session_profile |
npm package permalink returns http_403 |
npmjs.com presentation page is blocked and the URL is not eligible for the bundled package adapter | Use a direct /package/<name> permalink. Eligible package pages fall back to public latest-version metadata from registry.npmjs.org; this does not bypass Cloudflare or guarantee README content |
http_404 |
Bad link | Fix URL |
timeout |
Slow site, cold browser, or exhausted map/probe deadline | Retry; raise per-call timeout_ms for map/probe or OCCAM_BROWSER_TIMEOUT_MS for browser extracts |
response_too_large |
Page exceeds cap | Raise OCCAM_MAX_RESPONSE_BYTES or skip |
| Mojibake / wrong encoding | Rare worker edge | Report with URL; check UTF-8 chain |
MCP client¶
| Symptom | Cause | Fix |
|---|---|---|
| Tools hang | Browser pool saturated | Lower concurrency; check OCCAM_BROWSER_MAX_PARALLEL |
| Stale results after config change | Client cached old server | Reload MCP servers |
| WebSocket connection refused | Host not in WS mode | Start with --mcp-server |
Client schema lags the current release (urls still required; missing rank_blocks / emit_capsule…) or receipts report an older host version |
Old OccamMcp.Core.exe still mapped by a long-lived client/tunnel child, or the client cached tools/list |
Stop tunnel + host → republish/copy binary → start a fresh tunnel → reconnect the client. Verify with node scripts/check-public-mcp-contract.mjs |
Search and optional features¶
| Symptom | Cause | Fix |
|---|---|---|
search_unconfigured |
Provider off / incomplete config | Default is DuckDuckGo when unset; set OCCAM_SEARCH_PROVIDER=off to disable, or configure searxng/brave/tavily |
| Translation warning | No LibreTranslate | Set OCCAM_TRANSLATE_URL or omit translate_to |
| Unsigned receipts | Signing disabled | Unset OCCAM_RECEIPTS=off |
Diagnostic commands¶
$env:OCCAM_HOME = (Get-Location).Path
.\scripts\occam-doctor.ps1
node scripts/launch-mcp-host.mjs
node scripts/check-public-mcp-contract.mjs # tools/list contract + version-surface fingerprint
OccamMcp.Core.exe version-surface # hostVersion + assemblyPath
Enable profiler on stderr:
Still stuck?¶
- Note
failure.codeand full JSON response. - Check Failure codes for agent actions.
- Verify env: Configuration.