astrid-runtime/astrid · error

Failed to resolve Astrid home: {e}

Error message

Failed to resolve Astrid home: {e}

What it means

Thrown by `edit_config` when `astrid_core::dirs::AstridHome::resolve()` fails, i.e. the Astrid home directory (~/.astrid or $ASTRID_HOME) cannot be determined or created. The CLI needs the home root to locate `~/.astrid/etc/config.toml` before opening it in an editor. This is an environment/configuration resolution failure, not a file-format problem.

Source

Thrown at crates/astrid-cli/src/commands/config.rs:58

                for path in &resolved.loaded_files {
                    println!("  - {path}");
                }
            }
            Ok(())
        },
        Err(e) => {
            eprintln!("Configuration error: {e}");
            std::process::exit(1);
        },
    }
}

/// Open the global runtime config file (`~/.astrid/etc/config.toml`)
/// in `$EDITOR` (falling back to `$VISUAL`, then `vi`). Creates the
/// file if missing so the editor opens on a real path.
pub(crate) fn edit_config() -> Result<()> {
    let home = astrid_core::dirs::AstridHome::resolve()
        .map_err(|e| anyhow::anyhow!("Failed to resolve Astrid home: {e}"))?;
    let path = home.config_path();
    if !path.exists() {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        std::fs::write(&path, "# Astrid runtime configuration\n")?;
    }
    let editor = std::env::var("EDITOR")
        .ok()
        .or_else(|| std::env::var("VISUAL").ok())
        .unwrap_or_else(|| "vi".to_string());
    let status = std::process::Command::new(&editor)
        .arg(&path)
        .status()
        .map_err(|e| anyhow::anyhow!("Failed to launch '{editor}': {e}"))?;
    if !status.success() {
        anyhow::bail!("editor '{editor}' exited with non-zero status");
    }

View on GitHub (pinned to affd8760f4)

Solutions

1. Ensure HOME is set and writable (`echo $HOME`), or run as a user with a valid home directory.
2. Set ASTRID_HOME explicitly to an existing, writable directory: `export ASTRID_HOME=/path/to/astrid-home`.
3. Check the wrapped {e} text for the concrete cause (permission denied, path invalid) and fix that path's permissions.
4. Pre-create the home directory: `mkdir -p ~/.astrid/etc`.

Example fix

// before (shell)
astrid config edit
// after (shell)
export ASTRID_HOME="$HOME/.astrid"
mkdir -p "$ASTRID_HOME/etc"
astrid config edit

let home = std::env::var("ASTRID_HOME")
    .or_else(|_| std::env::var("HOME"))
    .map_err(|_| anyhow!("ASTRID_HOME or HOME must be set before `astrid config edit`"))?;
if !std::path::Path::new(&home).is_dir() {
    return Err(anyhow!("astrid home {home} does not exist"));
}

match AstridHome::resolve() {
    Err(e) => eprintln!("home resolve failed: {e}; set ASTRID_HOME to a writable dir"),
    Ok(home) => edit(home.config_path()),
}

When it happens

Trigger: Running `astrid config edit` when neither $ASTRID_HOME nor a usable home directory can be resolved (e.g. unset/invalid HOME, $ASTRID_HOME pointing at an unwritable or invalid path, or the resolver's create/verify step fails).

Common situations: Running under a service account or container with no HOME set; ASTRID_HOME set to a read-only mount; typo'd ASTRID_HOME path with permission-denied on create.

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

• HOME environment variable is not set
• no Capsule.toml in {} — run `astrid capsule check` from a ca
• Source path does not exist: {source}
• source path does not exist: {source}
• invalid value for {capsule_id}.{key}: expected one of {}, go

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