{"record":{"id":"8f98b08905ff14d5","repo":"astrid-runtime/astrid","slug":"resolve-astrid-home-for-revocation-file-e","errorCode":null,"errorMessage":"resolve $ASTRID_HOME for revocation file: {e}","messagePattern":"resolve \\$ASTRID_HOME for revocation file: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/astrid-gateway/src/revocations.rs","lineNumber":51,"sourceCode":"use std::path::PathBuf;\nuse std::sync::{Arc, RwLock};\n\nuse anyhow::Context;\nuse astrid_core::PrincipalId;\nuse astrid_storage::KvStore;\n\n/// Fixed host-only control namespace. Capsules never receive this scope.\npub const REVOCATION_NAMESPACE: &str = \"system:gateway:revocations\";\nconst PRINCIPAL_PREFIX: &str = \"principal/\";\nconst DEVICE_PREFIX: &str = \"device/\";\nconst MIGRATION_RECEIPT_KEY: &str = \"migration/legacy-json-v1\";\nconst MAX_REVOCATION_ENTRIES: usize = 1_000_000;\n\n/// Released JSON file under `etc/`, retained only as a one-time migration\n/// source. Runtime authority is the system control KV namespace above.\nfn revocations_path() -> anyhow::Result<PathBuf> {\n    let home = astrid_core::dirs::AstridHome::resolve()\n        .map_err(|e| anyhow::anyhow!(\"resolve $ASTRID_HOME for revocation file: {e}\"))?;\n    Ok(home.etc_dir().join(\"gateway-revocations.json\"))\n}\n\n/// Whether the released JSON index exists. Used only to fail closed when a\n/// standalone gateway has no authoritative KV wiring during startup.\npub fn legacy_file_exists() -> anyhow::Result<bool> {\n    let path = revocations_path()?;\n    match std::fs::symlink_metadata(&path) {\n        Ok(metadata) => {\n            if metadata.file_type().is_symlink() || !metadata.is_file() {\n                anyhow::bail!(\n                    \"legacy gateway revocation path is not a regular file: {}\",\n                    path.display()\n                );\n            }\n            Ok(true)\n        },\n        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-gateway/src/revocations.rs#L33-L69","documentation":"revocations_path resolves the $ASTRID_HOME directory via astrid_core::dirs::AstridHome::resolve to locate the legacy gateway-revocations.json file under etc/. If the home directory cannot be resolved (unset/invalid ASTRID_HOME or unresolvable home dir), the failure is wrapped in this error. Callers legacy_file_exists and migrate_legacy_file propagate it during startup checks.","triggerScenarios":"Calling legacy_file_exists() or migrate_legacy_file() when AstridHome::resolve() fails — ASTRID_HOME unset and no default home derivable, or ASTRID_HOME set to an unusable value.","commonSituations":"Running the gateway in a container/systemd unit without ASTRID_HOME set; ASTRID_HOME pointing at a relative or malformed path; user home directory unavailable for the service account.","solutions":["Set the ASTRID_HOME environment variable to an absolute, writable directory","Ensure the service user has a resolvable home directory if relying on the default","Check astrid_core::dirs::AstridHome::resolve docs for its resolution order and failure modes","Export ASTRID_HOME in the unit/container env (e.g. Environment=ASTRID_HOME=/var/lib/astrid)"],"exampleFix":"// before\n# systemd unit (no ASTRID_HOME)\n[Service]\nExecStart=/usr/bin/astrid-gateway\n// after\n[Service]\nEnvironment=ASTRID_HOME=/var/lib/astrid\nExecStart=/usr/bin/astrid-gateway","handlingStrategy":"validation","validationCode":"fn astrid_home_ready() -> bool {\n    std::env::var(\"ASTRID_HOME\")\n        .ok()\n        .map(|p| std::path::Path::new(&p).is_absolute())\n        .unwrap_or(false)\n}\n// fail fast at startup if !astrid_home_ready()","typeGuard":null,"tryCatchPattern":"match revocations::legacy_file_exists() {\n    Ok(exists) => exists,\n    Err(e) if e.to_string().contains(\"resolve $ASTRID_HOME\") => {\n        eprintln!(\"set ASTRID_HOME to an absolute directory\");\n        std::process::exit(2);\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Set ASTRID_HOME explicitly in systemd units, containers, and shells","Validate at process startup that ASTRID_HOME resolves and is writable","Document the env var in deployment manifests so it is never omitted"],"tags":["environment","configuration","paths"],"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"}