Skip to content
PatchArc

Troubleshooting

Symptoms, causes, and fixes for the observer, sealing, verification, login, and sharing.

validated against patcharc 0.2.0 · 2026-08-22

The capsule has no commits

Symptom: status shows commits: 0 after you committed, or the review's "What changed" is empty.

Cause: the observer was not running. Without --detach, start observes for 1.5 seconds and exits.

Fix: patcharc stop, then patcharc start --detach "<goal>". Confirm with cat .patcharc/observer.pid and tail .patcharc/observer.log. Commits made while no observer was running are not recorded retroactively in 0.2.0.

no active session

You ran note, decision, risk, checkpoint, or stop without an Arc. Run patcharc start --detach "<goal>" first. patcharc status tells you whether one is active.

start says an Arc is already active

Only one Arc per repository. Run patcharc stop to seal it, then start the next one. If the observer process is gone (for example after a reboot) stop still seals what was recorded.

The observer log shows git errors

The observer shells out to git. Make sure git --version works in the same environment, and that the repository is not in the middle of an interactive rebase when stop runs.

verify fails on a capsule I just sealed

Each issue is listed under ✗ … is INVALID. A hash mismatch means the file changed after sealing; a missing-entry issue means the ZIP was rewritten by another tool. Re-seal from the session if you still have it, or treat the file as tampered. A format_version mismatch means the capsule was produced by a different CLI version; 0.2.0 reads only 0.2.0 capsules.

patcharc doctor prints only two lines

Before init, only the git and .git checks print. After init you see the config and signing-key lines as well.

login returns 401 immediately

The API rejected the device request. This happens on deployments that require Turnstile for the device endpoint. The public api.patcharc.dev does not; if you run a private deployment, check its configuration.

The approval page says OAuth is not configured

The deployment has no GitHub or Google client configured. On patcharc.dev both are configured; on a private deployment set the OAUTH_* secrets.

The device code expired

Codes live for 10 minutes. Run patcharc login again and approve within that window.

share times out in verifying

The CLI polls for 2 minutes. Check the capsule directly:

$ TOKEN=$(jq -r .refresh_token ~/.patcharc/credentials.json)
$ curl -s https://api.patcharc.dev/v1/capsules/<capsule_id>/status -H "Authorization: Bearer $TOKEN" | jq '.status, .progress'

failed_terminal with a step error means server-side verification rejected the capsule; re-run patcharc verify locally and re-seal if needed. POST /v1/capsules/<id>/reprocess re-runs the pipeline.

The share was created with private or team visibility, which have no browser viewer yet. Create a new share with --visibility public (or capability), or PATCH /v1/shares/<id> with {"visibility":"public"}.

The share was revoked or expired. Create a new share from the same capsule; the capsule is still stored.

The capsule is still verifying. The response carries retry-after: 3; try again in a few seconds.

share uploads the wrong capsule

share picks the newest file in .patcharc/capsules/. Pass --file <path> to choose explicitly.

Credentials file permissions warning

~/.patcharc/credentials.json must be 0600 and ~/.patcharc 0700. Fix with chmod 700 ~/.patcharc && chmod 600 ~/.patcharc/credentials.json, or patcharc logout and login again.

Still stuck

Email hello@patcharc.dev with the output of patcharc --version, patcharc doctor, and the last 50 lines of .patcharc/observer.log. Security issues go to security@patcharc.dev.