{"record":{"id":"2f1d458676a8b802","repo":"astrid-runtime/astrid","slug":"home-is-required-to-choose-a-private-mountpoint","errorCode":null,"errorMessage":"HOME is required to choose a private mountpoint","messagePattern":"HOME is required to choose a private mountpoint","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage-provider-fskit/src/main.rs","lineNumber":458,"sourceCode":"        },\n    };\n    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()))?;","sourceCodeStart":440,"sourceCodeEnd":476,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage-provider-fskit/src/main.rs#L440-L476","documentation":"default_mountpoint derives a private mountpoint under the user's home directory; when the HOME environment variable is absent (home == None) there is no safe private location to choose, so it fails. This guard also ensures mountpoints are not placed in unpredictable shared locations.","triggerScenarios":"Calling prepare_mountpoint -> default_mountpoint with home: Option<OsString> == None, typically because the HOME env var is not set in the process environment.","commonSituations":"Running the fskit provider from a systemd unit or cron job with a minimal environment; launching via SSH with env resetting disabled; running inside a container without HOME set.","solutions":["Set the HOME environment variable before running the provider (export HOME=/Users/you or /home/you).","In a service unit, set Environment=HOME=/var/lib/astrid or pass an explicit mountpoint instead of relying on the default.","Ensure HOME is absolute, since a relative HOME fails the next check."],"exampleFix":"// before (service unit with no env)\nExecStart=/usr/local/bin/astrid-storage-provider-fskit mount\n// after\nEnvironment=HOME=/var/lib/astrid\nExecStart=/usr/local/bin/astrid-storage-provider-fskit mount","handlingStrategy":"validation","validationCode":"if !process.env.HOME || !path.isAbsolute(process.env.HOME) {\n  throw new Error(\"HOME must be set and absolute before mounting\");\n}","typeGuard":"fn has_absolute_home(env: &std::collections::HashMap<String, String>) -> Option<&str> {\n    env.get(\"HOME\").filter(|h| std::path::Path::new(h).is_absolute()).map(|s| s.as_str())\n}","tryCatchPattern":"match default_mountpoint(std::env::var_os(\"HOME\"), &view) {\n    Ok(mp) => mount_at(mp).await,\n    Err(e) => eprintln!(\"cannot choose mountpoint: {e:#}; set HOME explicitly\"),\n}","preventionTips":["Set HOME in service units, cron jobs, and containers (Environment=HOME=...).","Prefer passing an explicit mountpoint instead of relying on the HOME-derived default.","Verify HOME is absolute — relative HOME passes the presence check but fails the next one."],"tags":["environment","mountpoint","rust"],"backgroundTag":"missing-env-var","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"}