signaturePolicy=required-cosign-v1 requires the cosign CLI on PATH |
Published v1.0.0-rc.3+ verifies a Cosign bundle and does not install Cosign for you |
Install Cosign so cosign is on PATH, then re-run the bootstrap |
occam contract reports schemaFingerprint mismatch on published 1.3.0 |
The 1.3.0 contract check spawned the default reader profile (11 tools). The fingerprint file is the full catalog (18) |
OCCAM_PROFILE=full occam contract. A later release sets that default inside the check |
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 install/repo root; run occam doctor or occam install-workers |
ERR_MODULE_NOT_FOUND / @mozilla/readability (worker crash) |
workers/node_modules empty or corrupt (doctor used to skip install when the directory merely existed) |
occam install-workers --force (or OCCAM_WORKERS_FORCE_INSTALL=1 + occam doctor). Verify: node scripts/lib/ensure-workers-deps.mjs --check → WORKERS_DEPS_OK |
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.2.0 |
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 |