Troubleshoot multisig

Use this guide when the multisig signing flow fails or a production drive ends up in a bad state. For general desktop OTA and staging problems, see Troubleshoot desktop releases.

Request refused: source not healthily seeded

hyper-multisig request refuses to issue a signing request if the source provision drive is not healthily seeded. Reseed the provision drive on more peers, then retry:

pear seed pear://<provision-link>

Keep always-on seeders for the provision link so requests do not depend on a single network path.

Interrupted or aborted commit

Do not abort a running commit. If a commit gets interrupted (crash, power loss, premature Ctrl+C), the production build is stuck in an intermediate state.

The request and responses are enough to finish the commit, and the commit does not have to run on the same machine that prepared the request. Run the commit again as soon as possible:

hyper-multisig commit [--first-commit] <signing request> <response-1> <response-2> ...

From the second commit onwards, a misuse can corrupt the production build. If hyper-multisig errors with INCOMPATIBLE_SOURCE_AND_TARGET, do not work around it — see below.

INCOMPATIBLE_SOURCE_AND_TARGET

INCOMPATIBLE_SOURCE_AND_TARGET from hyper-multisig commit means the source provision drive and the multisig target have diverged in a way the tool refuses to reconcile. Do not work around this — working around it can corrupt the production build. Reseed the provision drive on more peers and retry the commit:

pear seed pear://<provision-link>

Recovering lost write access

• Staged and provisioned drives are machine-bound in normal setups — if you lose the data that holds write capability to those keys, you cannot "undelete" the same keys from thin air.
• Multisig production drives are not machine-bound. Write access is determined by signing capability, so a quorum of signers can keep producing releases even if every other key is lost.

If a provision key is lost and you already have a multisig production drive, you can rebuild a clean provision drive from production. Mint a fresh target key with pear touch, then run two pear provision commands in order:

# 1. Seed the new target with the production drive's current contents
pear provision <versioned-production-key> <target-key> <versioned-production-key>

# 2. Sync from the most recent stage onto the new target, anchored on production
pear provision <versioned-stage-key> <target-key> <versioned-production-key>

Then update srcKey in multisig.json to the new provision target's key (see Create the multisig config).

To automate this in CI, the pear-provision-recover action rebuilds a writable provision drive from a remote key — pass the lost drive's key, target length/blobs-length, and a fresh primary-key and name.

See also

• Set up multisig — generate keys, write multisig.json, and point upgrade at the multisig link.
• Sign with multisig — the prepare → sign → verify → commit flow.
• Troubleshoot desktop releases — OTA, seeding, and staging problems.
• Release pipeline — conceptual diagrams for stage, provision, and multisig.