{"record":{"id":"dc690023a6a58ce9","repo":"astrid-runtime/astrid","slug":"resolve-durable-principal-uid-error","errorCode":null,"errorMessage":"resolve durable principal UID: {error}","messagePattern":"resolve durable principal UID: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-capsule-install/src/lifecycle.rs","lineNumber":157,"sourceCode":"/// directory. The immutable UID is resolved before any secret scope is built;\n/// callers that only have a mutable alias must use this entry point rather\n/// than deriving a namespace from alias text.\n#[allow(clippy::too_many_arguments)]\npub fn run_lifecycle_for_principal_with_storage(\n    target_dir: &Path,\n    wasm_bytes: Vec<u8>,\n    manifest: &CapsuleManifest,\n    home: &AstridHome,\n    target_principal: &PrincipalId,\n    storage: &RuntimePrincipalStore,\n    phase: LifecyclePhase,\n    previous_version: Option<&str>,\n    external_bus: Option<EventBus>,\n) -> anyhow::Result<()> {\n    let directory = storage.principal_directory();\n    let uid = directory\n        .uid_for(target_principal)\n        .map_err(|error| anyhow::anyhow!(\"resolve durable principal UID: {error}\"))?;\n    run_lifecycle_in_scope(\n        target_dir,\n        wasm_bytes,\n        manifest,\n        Some(home),\n        target_principal,\n        Some(uid),\n        Some(storage.clone()),\n        phase,\n        previous_version,\n        external_bus,\n    )\n}\n\n#[allow(clippy::too_many_arguments)]\nfn run_lifecycle_in_scope(\n    target_dir: &Path,\n    wasm_bytes: Vec<u8>,","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-capsule-install/src/lifecycle.rs#L139-L175","documentation":"run_lifecycle_for_principal_with_storage resolves the durable principal's UID via the principal directory before running lifecycle operations; if uid_for fails (directory corruption, missing mapping), the underlying error is wrapped as 'resolve durable principal UID: {error}' with full context.","triggerScenarios":"install_from_local_path_internal invokes the lifecycle runner for a target_principal whose entry is absent or unreadable in storage.principal_directory(), so uid_for returns an Err.","commonSituations":"Installing/upgrading a capsule for a principal that was never registered; damaged principal-directory index on disk; principal identifier casing/format mismatch.","solutions":["Register the principal (or run an initial install) before lifecycle operations","Verify the principal identifier matches the registered one exactly","Repair or rebuild the principal directory storage","Inspect the wrapped {error} message for the underlying cause"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"fn principal_registered(storage: &Storage, p: &Principal) -> bool {\n    storage.principal_directory().uid_for(p).is_ok()\n}","typeGuard":null,"tryCatchPattern":"match run_lifecycle_for_principal_with_storage(...) {\n    Err(e) if e.to_string().starts_with(\"resolve durable principal UID\") => {\n        eprintln!(\"principal not registered in directory: register it first\");\n    }\n    other => other?,\n}","preventionTips":["Ensure an initial install/registration exists before upgrades or lifecycle ops","Verify principal identifier spelling and format","Back up and integrity-check the principal directory storage"],"tags":["lifecycle","principal","storage","install"],"backgroundTag":"entity-not-found","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}