Troubleshooting

Refusals a newcomer actually hits, in the Tutorial’s own sequence, each quoted verbatim from the CLI. If a message here reads as confusing, that is worth reporting — this page explains what exists today; it does not change any wording.

error: author signing is required: set PRIKK_AUTHOR_KEY_ID (no signing key configured)

You ran commit without PRIKK_AUTHOR_KEY_ID/PRIKK_AUTHOR_SEED set. Every commit produces a signed Patch; there is no unsigned path. Set both variables — see Security and Signing Setup — and commit again.

error: PRIKK_AUTHOR_SEED must be 64 hex characters, got 8

PRIKK_AUTHOR_SEED must be exactly 64 lowercase hex characters (32 raw bytes) — the number after got reports how many characters your value actually had, so it will differ from the 8 shown here. A shorter, longer, or non-hex value is rejected before anything is signed — nothing is written to the repository when this fires. The same check applies to PRIKK_MAINTAINER_SEED.

error: invalid name: worktree has no node-addressed changes to commit

You ran commit with nothing changed since the last commit or seal — no new, edited, or deleted files for Prikk to record. Change something first.

error: maintainer signing is required: set PRIKK_MAINTAINER_KEY_ID (no signing key configured)

You ran seal without PRIKK_MAINTAINER_KEY_ID/PRIKK_MAINTAINER_SEED set. seal needs a maintainer key, distinct from the author key commit used — see why the tutorial needs a second key. Set both variables and seal again.

error: integrity error: publication trust policy is missing or unreadable

Your maintainer key is configured but not yet trusted by this repository. Run prikk trust maintainer add --key-id ID --public-key HEX with the public half of your maintainer key, then seal again. This is a repository-local, trust-on-first-use step — every fresh repository needs it once, even with a key you have used elsewhere.

error: active WAL has no patch records to seal

You ran seal with nothing queued — every commit since the last seal has already been published. There is nothing to fix; commit something before sealing again.

error: invalid name: ref topic is not a local branch ref; expected heads/<name>

You passed a bare name (topic) where Prikk expects a fully-qualified ref (heads/topic). branch create, branch close, tag create, and any --ref flag all take the qualified form — see why refs are fully qualified for the reasoning. Re-run the same command with heads/ (or tags/ for a tag) in front of the name.

error: i/o error: repository mutation requires Linux, macOS, or Windows root-scoped filesystem capabilities

You are running init, commit, or seal on a platform other than Linux, macOS, or Windows. Reading commands (verify, log, status, doctor) work anywhere Prikk builds; mutation does not, by design — see Platform Support.

Something not listed here

Run prikk doctor — it is the diagnostic-first command, and its recommendation lines usually name the next step. If it does not, the message is real (Prikk does not invent placeholder diagnostics) but this page has not caught up with it yet.