astrid-runtime/astrid · error · anyhow::Error

resolve $ASTRID_HOME for revocation file

Error message

resolve $ASTRID_HOME for revocation file: {e}

What it means

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.

Solutions

1. Set the ASTRID_HOME environment variable to an absolute, writable directory
2. Ensure the service user has a resolvable home directory if relying on the default
3. Check astrid_core::dirs::AstridHome::resolve docs for its resolution order and failure modes
4. Export ASTRID_HOME in the unit/container env (e.g. Environment=ASTRID_HOME=/var/lib/astrid)

Example fix

// before
# systemd unit (no ASTRID_HOME)
[Service]
ExecStart=/usr/bin/astrid-gateway
// after
[Service]
Environment=ASTRID_HOME=/var/lib/astrid
ExecStart=/usr/bin/astrid-gateway

fn astrid_home_ready() -> bool {
    std::env::var("ASTRID_HOME")
        .ok()
        .map(|p| std::path::Path::new(&p).is_absolute())
        .unwrap_or(false)
}
// fail fast at startup if !astrid_home_ready()

match revocations::legacy_file_exists() {
    Ok(exists) => exists,
    Err(e) if e.to_string().contains("resolve $ASTRID_HOME") => {
        eprintln!("set ASTRID_HOME to an absolute directory");
        std::process::exit(2);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Failed to resolve ASTRID_HOME for token path
• Failed to resolve ASTRID_HOME for handshake
• Astrid volume path has no file name
• ASTRID_WORKSPACE_STATE_DIR must be valid UTF-8
• canonical Astrid workspace requires the kernel workspace…

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/8f98b08905ff14d5. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-gateway/src/revocations.rs:51

use std::path::PathBuf;
use std::sync::{Arc, RwLock};

use anyhow::Context;
use astrid_core::PrincipalId;
use astrid_storage::KvStore;

/// Fixed host-only control namespace. Capsules never receive this scope.
pub const REVOCATION_NAMESPACE: &str = "system:gateway:revocations";
const PRINCIPAL_PREFIX: &str = "principal/";
const DEVICE_PREFIX: &str = "device/";
const MIGRATION_RECEIPT_KEY: &str = "migration/legacy-json-v1";
const MAX_REVOCATION_ENTRIES: usize = 1_000_000;

/// Released JSON file under `etc/`, retained only as a one-time migration
/// source. Runtime authority is the system control KV namespace above.
fn revocations_path() -> anyhow::Result<PathBuf> {
    let home = astrid_core::dirs::AstridHome::resolve()
        .map_err(|e| anyhow::anyhow!("resolve $ASTRID_HOME for revocation file: {e}"))?;
    Ok(home.etc_dir().join("gateway-revocations.json"))
}

/// Whether the released JSON index exists. Used only to fail closed when a
/// standalone gateway has no authoritative KV wiring during startup.
pub fn legacy_file_exists() -> anyhow::Result<bool> {
    let path = revocations_path()?;
    match std::fs::symlink_metadata(&path) {
        Ok(metadata) => {
            if metadata.file_type().is_symlink() || !metadata.is_file() {
                anyhow::bail!(
                    "legacy gateway revocation path is not a regular file: {}",
                    path.display()
                );
            }
            Ok(true)
        },
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),

View on GitHub (pinned to affd8760f4)