{"record":{"id":"f81ebcc0e8142013","repo":"astrid-runtime/astrid","slug":"an-incomplete-capsule-authority-update-exists-at","errorCode":null,"errorMessage":"an incomplete capsule authority update exists at {}; remove it only after inspecting the interrupted install","messagePattern":"an incomplete capsule authority update exists at (.+?); remove it only after inspecting the interrupted install","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-capsule-install/src/authority.rs","lineNumber":369,"sourceCode":"\nimpl AuthorityReceiptTransaction {\n    pub(crate) fn stage(\n        home: &AstridHome,\n        target_dir: &Path,\n        authority: &InstalledAuthority,\n    ) -> anyhow::Result<Self> {\n        let paths = authority_paths(home, target_dir)?;\n        astrid_core::platform_fs::ensure_private_directory(&paths.directory).with_context(\n            || {\n                format!(\n                    \"failed to secure capsule authority directory {}\",\n                    paths.directory.display()\n                )\n            },\n        )?;\n\n        if paths.pending.exists() {\n            bail!(\n                \"an incomplete capsule authority update exists at {}; remove it only after inspecting the interrupted install\",\n                paths.pending.display()\n            );\n        }\n        if paths.previous.exists() && paths.active.exists() {\n            std::fs::remove_file(&paths.previous).with_context(|| {\n                format!(\n                    \"failed to clean stale capsule authority backup {}\",\n                    paths.previous.display()\n                )\n            })?;\n        }\n        if paths.previous.exists() && !paths.active.exists() {\n            std::fs::rename(&paths.previous, &paths.active).with_context(|| {\n                format!(\n                    \"failed to recover capsule authority backup {}\",\n                    paths.previous.display()\n                )","sourceCodeStart":351,"sourceCodeEnd":387,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-capsule-install/src/authority.rs#L351-L387","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nAuthorityReceiptTransaction::stage(&home, &target_dir, &new_authority)?;\n// after\nif authority_pending_path(&home, &target_dir).exists() {\n    resolve_pending_transaction(&home, &target_dir)?; // inspect, commit or drop\n}\nAuthorityReceiptTransaction::stage(&home, &target_dir, &new_authority)?;","handlingStrategy":"validation","validationCode":"if authority_pending_path(&home, &target_dir).exists() {\n    return Err(anyhow!(\"stale pending authority transaction; resolve before staging\"));\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["capsule","install-transaction","concurrency","rust"],"backgroundTag":"conflicting-config-options","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}