an incomplete capsule authority update exists at {}; remove

Error message

an incomplete capsule authority update exists at {}; remove it only after inspecting the interrupted install

What it means

stage() rejects staging a new authority receipt when a pending receipt from a previous (interrupted) transaction still exists. Only one transaction may be in flight; a leftover pending file means the prior install was never committed or cleaned up. The error directs the operator to inspect the interrupted install before deleting the marker.

Source

Thrown at crates/astrid-capsule-install/src/authority.rs:369

impl AuthorityReceiptTransaction {
    pub(crate) fn stage(
        home: &AstridHome,
        target_dir: &Path,
        authority: &InstalledAuthority,
    ) -> anyhow::Result<Self> {
        let paths = authority_paths(home, target_dir)?;
        astrid_core::platform_fs::ensure_private_directory(&paths.directory).with_context(
            || {
                format!(
                    "failed to secure capsule authority directory {}",
                    paths.directory.display()
                )
            },
        )?;

        if paths.pending.exists() {
            bail!(
                "an incomplete capsule authority update exists at {}; remove it only after inspecting the interrupted install",
                paths.pending.display()
            );
        }
        if paths.previous.exists() && paths.active.exists() {
            std::fs::remove_file(&paths.previous).with_context(|| {
                format!(
                    "failed to clean stale capsule authority backup {}",
                    paths.previous.display()
                )
            })?;
        }
        if paths.previous.exists() && !paths.active.exists() {
            std::fs::rename(&paths.previous, &paths.active).with_context(|| {
                format!(
                    "failed to recover capsule authority backup {}",
                    paths.previous.display()
                )

View on GitHub (pinned to affd8760f4)

Solutions

Inspect the pending receipt, then commit or discard the previous AuthorityReceiptTransaction before staging a new one
Ensure no other install process is running on this capsule directory, then remove the pending file and retry
Reinstall the capsule cleanly (delete the authority directory after inspection) to reset the transaction state

Example fix

// before
AuthorityReceiptTransaction::stage(&home, &target_dir, &new_authority)?;
// after
if authority_pending_path(&home, &target_dir).exists() {
    resolve_pending_transaction(&home, &target_dir)?; // inspect, commit or drop
}
AuthorityReceiptTransaction::stage(&home, &target_dir, &new_authority)?;

Defensive patterns

Strategy: validation

Validate before calling

if authority_pending_path(&home, &target_dir).exists() {
    return Err(anyhow!("stale pending authority transaction; resolve before staging"));
}

Prevention

Always pair stage() with commit() in a scoped helper so failures clean up
Use file locking to prevent concurrent installs into the same capsule directory
After crashes, run a recovery/inspection step before retrying installs

When it happens

Trigger: Calling AuthorityReceiptTransaction::stage when paths.pending exists — typically after a previous stage() that never reached commit(), or a concurrent install in the same target_dir.

Common situations: Interrupted capsule upgrade (process killed mid-install); two install processes racing on the same capsule directory; retried install after a crash without cleaning the pending receipt.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/f81ebcc0e8142013. Report an issue: GitHub.