{"record":{"id":"2834ebca4eed5767","repo":"astrid-runtime/astrid","slug":"home-must-be-absolute-to-choose-a-private-mountpoi","errorCode":null,"errorMessage":"HOME must be absolute to choose a private mountpoint","messagePattern":"HOME must be absolute to choose a private mountpoint","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage-provider-fskit/src/main.rs","lineNumber":460,"sourceCode":"    if existed {\n        validate_unmounted_mountpoint(&mountpoint)?;\n    } else {\n        astrid_core::platform_fs::ensure_private_directory(&mountpoint)\n            .with_context(|| format!(\"create private mountpoint {}\", mountpoint.display()))?;\n        validate_unmounted_mountpoint(&mountpoint)?;\n    }\n    Ok((mountpoint, !existed))\n}\n\nfn default_mountpoint(\n    home: Option<std::ffi::OsString>,\n    view: &astrid_core::storage_provider::StorageProviderViewV1,\n) -> Result<PathBuf> {\n    let home = home\n        .map(PathBuf::from)\n        .ok_or_else(|| anyhow::anyhow!(\"HOME is required to choose a private mountpoint\"))?;\n    if !home.is_absolute() {\n        bail!(\"HOME must be absolute to choose a private mountpoint\");\n    }\n    let leaf = match view {\n        astrid_core::storage_provider::StorageProviderViewV1::Principal(principal) => {\n            principal.to_string()\n        },\n        astrid_core::storage_provider::StorageProviderViewV1::Fleet(fleet) => fleet.to_string(),\n        astrid_core::storage_provider::StorageProviderViewV1::Admin => \"system\".to_owned(),\n    };\n    Ok(home.join(\"Astrid\").join(leaf))\n}\n\nfn validate_unmounted_mountpoint(mountpoint: &Path) -> Result<()> {\n    validate_mountpoint_layout(mountpoint)?;\n    validate_mountpoint_ancestors(mountpoint)?;\n    astrid_core::platform_fs::verify_no_redirects(mountpoint)\n        .with_context(|| format!(\"reject redirected mountpoint {}\", mountpoint.display()))?;\n    astrid_core::platform_fs::validate_private_directory(mountpoint)\n        .with_context(|| format!(\"reject unsafe mountpoint {}\", mountpoint.display()))?;","sourceCodeStart":442,"sourceCodeEnd":478,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage-provider-fskit/src/main.rs#L442-L478","documentation":"default_mountpoint() builds the fallback mount path as $HOME/Astrid/<principal>, requiring HOME to be set AND an absolute path; a relative HOME would produce a mountpoint that depends on the process cwd. This bail fires when HOME exists but is relative (e.g. 'home/user'). A missing HOME yields the sibling 'HOME is required' error instead.","triggerScenarios":"No explicit mountpoint passed to the mount request and std::env::var_os(\"HOME\") yields a value whose is_absolute() is false, so default_mountpoint() (via prepare_mountpoint) bails.","commonSituations":"Running the provider in a container, systemd unit, or CI where HOME is set to a relative or bogus value; shells with HOME='.' or '~/'; test harnesses overriding HOME incorrectly.","solutions":["Set HOME to an absolute path (e.g. HOME=/root or HOME=/home/alice) before launching the provider.","Or pass an explicit absolute mountpoint in the mount request so default_mountpoint() is never consulted.","Fix the environment/unit file that exports a relative HOME."],"exampleFix":"// before\nHOME=./homedir astrid-fskit-provider\n// after\nHOME=/home/alice astrid-fskit-provider\n# or request an explicit mountpoint in the mount request","handlingStrategy":"validation","validationCode":"fn home_is_usable() -> bool {\n    std::env::var_os(\"HOME\")\n        .map(|h| PathBuf::from(&h).is_absolute())\n        .unwrap_or(false)\n}\n// if false, pass an explicit absolute mountpoint in the request","typeGuard":"fn valid_home(home: &Option<std::ffi::OsString>) -> bool {\n    home.as_ref().map(|h| PathBuf::from(h).is_absolute()).unwrap_or(false)\n}","tryCatchPattern":"match result {\n    Err(e) if e.to_string().contains(\"HOME must be absolute\") => {\n        // fall back to explicit mountpoint or fix environment and retry\n    },\n    other => other,\n}","preventionTips":["Always export an absolute HOME in containers, systemd units, and CI.","Pass an explicit mountpoint instead of relying on HOME-derived defaults.","Validate HOME with Path::is_absolute() at process startup."],"tags":["env-var","home","mountpoint","config"],"backgroundTag":"invalid-env-var-value","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}