Troubleshooting

Errors you may meet and what they mean.

Messages you may see, what they mean, what to do. Start with secretree doctor: it runs every check below and prints the fix next to each failure.

Installation

fatal: Unable to find remote helper for 'secretree' git cannot see git-remote-secretree on its PATH. Run secretree install-helper --dir <a directory on PATH> (for example /usr/local/bin), or put the secretree binary itself in such a directory and run install-helper again. GUI git clients often have a shorter PATH than your shell.

A Keychain dialog appears on every command (macOS) Click "Always Allow" once for secretree and, separately, for git-remote-secretree (macOS treats the symlink as a second program).

keys for vault … are not in the file (…) on Linux No Secret Service was available, so keys went into the file store under ~/.config/secretree/keys. Install libsecret-tools to use the Secret Service from now on; existing file-store keys are still read when SECRETREE_KEYSTORE=file.

Vault and sync

vault rejected the push: another writer appended a generation first Someone pushed between your fetch and your push. git fetch, merge or rebase, push again; exactly like any other remote.

! [remote rejected] main -> main (vault rejected (someone pushed first; fetch and retry)) The same situation seen through git.

vault rolled back: this device recorded generation 000042 on the host, the host now ends at 000040 The host (or someone with its credentials) removed or replaced generations. Nothing is lost locally. Run secretree verify to see what remains, then secretree repair on a device that holds the data; it rebuilds the chain and proves it restorable. Protect the vault branch on the host and rotate its credentials.

WARNING: pr/…/….json was removed upstream by bob (5070123); restored from local objects Someone pushed a collaboration history with that event missing. Your client put it back and pushed the union; the named commit shows who. Nothing to do unless it keeps happening, in which case secretree member remove the device.

existing chain failed verification, refusing to append The vault on the remote does not verify: a broken hash chain, a bad signature or an unreadable manifest. secretree will not write on top of it. Run secretree verify --quick to see which generation fails. If the host rolled the vault back, the last good state is what the chain shows; if a blob is corrupt, restore from the previous generation and start a new full one with backup --full.

generation 000003: opaque (predates this key) This device's key was added after that generation was written, so it cannot read it; the signature and chain link were still verified. Everything from the full generation written at your approval onward is readable, including the whole git history.

the vault holds several repositories; pass --repo-id Use secretree clone <vault>#<repo-id> or git clone secretree::<vault>#<repo-id>. secretree restore without --repo-id lists them with their labels.

vault is empty; run secretree init first The remote has no commits. init bootstraps it; clone and the helper need an existing vault.

recovery kit is for vault X but the remote holds vault Y Wrong kit for this remote.

Pull requests

cannot merge: needs 1 approval(s) of 900c2a69, has 0 Approvals count only for the current head commit. After a new push, ask for a new approval.

cannot merge: required check "ci" has not run for 900c2a69 No runner has processed this commit yet. Start one with secretree runner --once on a machine that holds a key.

cannot merge: this device is an agent; a person has to merge Agent members cannot merge. Merge from a person's device or the UI.

branch feature is not on the vault yet: git push origin feature pr open needs the head branch pushed first.

A line comment shows as "outdated" The line it was anchored to changed or was removed in a later push. The comment stays in the conversation with the commit it referred to.

Runner and deploy

no pipeline: add .secretree/ci, a ci make target, or run the runner with --cmd The runner found nothing to execute in that commit.

deploy: waiting for check "ci" on 4ebfacfe (with -v) The branch tip has no green check yet; the deploy agent waits. Use --require-check "" to deploy without a gate.

The job ran but secretree pr comment inside it failed with not initialised Use secretree -C "$SECRETREE_REPO_DIR" …: the job runs in a throw-away worktree, the runner's clone holds the configuration.

Windows notes

The helper is a copy named git-remote-secretree.exe; keep it next to secretree.exe. Pipelines, hooks and watch --exec commands run through cmd.exe. schedule and ui --install are not available; use Task Scheduler. Keys use the file store under %APPDATA%\secretree.

Getting help

Open an issue at github.com/buildsnap-dev/secretree with the command, its output and secretree -v status. For anything security-related, use a private advisory instead.