Troubleshooting

The issues users actually hit, in rough order of frequency.

shipmoor: command not found after install

The installer puts the binary at ~/.shipmoor/bin/shipmoor and never edits your shell profile silently — it prints the exact export PATH line instead. If the command isn’t found, add that line to your shell rc and reload:

export PATH="$HOME/.shipmoor/bin:$PATH"

In CI, append the directory to the path mechanism your runner uses (on GitHub Actions: echo "$HOME/.shipmoor/bin" >> $GITHUB_PATH), or call the binary by its absolute path.

The installer requires curl, tar, python3, and sha256sum or shasum. Intel Macs (darwin-amd64) are not supported in this release.

A full-repo scan reports a wall of phantom imports

A full shipmoor scan . on a project whose third-party dependencies aren’t declared where Shipmoor can see them (no manifest, or a bare checkout without requirements.txt) reports many missing_manifest_entry / unresolved_local_module findings. That’s the resolver being honest about what it can’t resolve — but it’s noise if you only care about your change.

Two fixes, in order of preference:

1. Scope to the change. --changed, --staged, or --diff <range> is what the agent loop and CI should use anyway; with diff.only_introduced: true (the default) the gate only counts what the change introduced.
2. Declare the project’s dependencies. A requirements.txt / package.json / go.mod at the project root gives the resolvers the manifest context they need. The context line of the output tells you what was found — degraded resolvers means no manifest was discovered.

Paid features locked even though I subscribed

Work through it in this order:

shipmoor whoami            # authenticated? plan? reason?
shipmoor capabilities --json

• reason: missing / not_logged_in — no license on this machine; run shipmoor login.
• reason: expired_in_grace / expired_past_grace — renew or re-login; past grace the binary behaves as Community by design.
• reason: missing_entitlement — signed in, but the account doesn’t carry that feature; check your plan at accounts.shipmoor.dev.
• old_community_binary — a pre-universal build; run shipmoor upgrade, then login.
• In CI — make sure SHIPMOOR_LICENSE_TOKEN (or SHIPMOOR_LICENSE_FILE) is actually injected into the job’s environment.

See Sign in & licensing for the full reason-code list.

CI treats a finding as a tooling failure

Exit code 1 means the gate fired — findings met the --fail-on threshold; the JSON/SARIF report is complete and should still be uploaded. Only 2 (usage error) and 3 (scan crashed) are tooling failures, and only those runs lack a report. Pattern your pipeline accordingly — see SARIF & code scanning.

No claim check appears on my scan

The claim check requires both a diff-bearing scope (--changed / --staged / --diff / --patch) and an intent source (--intent, --prompt, --session, or .shipmoor/intent.txt) — plus the intent_scan entitlement. A plain path scan, or a scan with no intent, is a normal structural scan. See Providing intent.

The claim-check gate won’t block

By design, mostly. The floor refuses to block when the intent confidence is low (one source), the result is unprobed/inferred, or the evidence isn’t deterministic. Run with --would-block to see the gate’s reasoning, and add a second agreeing intent source. See Turning on the gate.

shipmoor upgrade fails

upgrade has its own exit codes: 20 network/manifest fetch, 21 checksum mismatch (retry; if persistent, report it), 22 permission or install-path error, 23 atomic replacement failed (the original install is left intact). Windows isn’t supported by upgrade — install manually from dl.shipmoor.dev.

Still stuck?

Capture shipmoor version, the exact command, and the stderr output. For scan issues, a --json report (it contains findings, paths, and rule IDs — no source) is the most useful artifact to share.

Next

• Installation — channels, pinning, and verification.
• Output formats & exit codes — the full exit-code contract.
• Capabilities & entitlements — decoding the entitlement state.