astrid-runtime/astrid · warning

update notices require an initialized Astrid home

Error message

update notices require an initialized Astrid home

What it means

cache_path_for only returns the update-notice cache file when the resolved Astrid home reports the current layout version. If the home directory is missing, fresh, or was created by an older/newer layout, the code refuses to cache update notices rather than create state inside an undeclared home. It fails fast so notice caching never implicitly initializes a home directory.

Solutions

  1. Initialize the Astrid home first (run the init/setup command or create a session) so its layout version matches LAYOUT_VERSION.
  2. If ASTRID_HOME points at the wrong place, unset or correct the environment variable to the initialized home.
  3. If the home is stale from an old version, re-initialize/migrate it to the current layout.

Example fix

// before
export ASTRID_HOME=/tmp/fresh-home   # uninitialized
astrid doctor                         # error: update notices require an initialized Astrid home

// after
astrid init                            # or: unset ASTRID_HOME to use the real initialized home
astrid doctor
Defensive patterns

Strategy: fallback

Validate before calling

let home = astrid_core::dirs::AstridHome::resolve()?;
let initialized = home.layout_version()?.as_deref()
    == Some(astrid_core::dirs::LAYOUT_VERSION);
if !initialized { eprintln!("home not initialized; skipping update notice cache"); }

Try / catch

match cache_path() {
    Ok(path) => read_notice_cache(&path),
    Err(_) => Ok(None), // notices are best-effort; degrade silently
}

Prevention

When it happens

Trigger: Calling any command that consults update notices before `astrid init` (or equivalent) has created an initialized home, or when ASTRID_HOME points to an empty/new directory, or the home was produced by a different layout version.

Common situations: Running astrid in CI or a container with a fresh/empty ASTRID_HOME; users who deleted their home dir; version mismatch after an upgrade that changed the layout version; tests deliberately pointing at a nonexistent home.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at crates/astrid-cli/src/commands/self_update_notice.rs:28

    CHECK_TTL_SECS, CURRENT_VERSION, InstallMethod, UpdateChannel, platform_target, resolve_repo,
    running_binary, update_channel,
};

#[derive(serde::Serialize, serde::Deserialize)]
struct UpdateCache {
    checked_at: u64,
    latest_version: String,
    channel: String,
}

fn cache_path() -> anyhow::Result<PathBuf> {
    let home = astrid_core::dirs::AstridHome::resolve()?;
    cache_path_for(&home)
}

fn cache_path_for(home: &astrid_core::dirs::AstridHome) -> anyhow::Result<PathBuf> {
    if home.layout_version()?.as_deref() != Some(astrid_core::dirs::LAYOUT_VERSION) {
        bail!("update notices require an initialized Astrid home");
    }
    Ok(home.var_dir().join("update-check.json"))
}

fn now_epoch() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |duration| duration.as_secs())
}

pub(super) fn write_cache(channel: UpdateChannel, version: &str) {
    let cache = UpdateCache {
        checked_at: now_epoch(),
        latest_version: version.to_owned(),
        channel: channel.as_str().to_owned(),
    };
    if let Ok(path) = cache_path()
        && let Ok(json) = serde_json::to_string(&cache)

View on GitHub (pinned to affd8760f4)