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

InvalidData

InvalidData

Error message

unsupported Astrid home layout version {other:?}

What it means

capture_layout_origin classifies an Astrid home by reading its layout-version sentinel file. The version string it found is not absent (fresh), not the legacy version, and not the current LAYOUT_VERSION (v2), so the home was written by an unknown/newer or corrupt version and the library refuses to guess, throwing InvalidData.

Source

Thrown at crates/astrid-kernel/src/legacy_migration_barrier/mod.rs:98

/// Layout state captured before `AstridHome::ensure` can create a v2
/// sentinel.  A bool cannot distinguish a brand-new home from a cut-over
/// home that lost its completion ledger.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(not(unix), allow(dead_code))]
pub(crate) enum LayoutOrigin {
    Fresh,
    Legacy,
    ExistingV2,
}

#[cfg(any(unix, test))]
pub(crate) fn capture_layout_origin(home: &AstridHome) -> io::Result<LayoutOrigin> {
    match home.layout_version()?.as_deref() {
        None => Ok(LayoutOrigin::Fresh),
        Some(astrid_core::dirs::LEGACY_LAYOUT_VERSION) => Ok(LayoutOrigin::Legacy),
        Some(LAYOUT_VERSION) => Ok(LayoutOrigin::ExistingV2),
        Some(other) => Err(io::Error::new(
            io::ErrorKind::InvalidData,
            format!("unsupported Astrid home layout version {other:?}"),
        )),
    }
}

/// Path of the global migration ledger.
#[must_use]
pub(crate) fn ledger_path(home: &AstridHome) -> PathBuf {
    home.migrations_dir().join(LEDGER_NAME)
}

/// Reject an existing layout-two home that was cut over without the complete
/// component ledger.  Fresh homes have no sentinel yet and are admitted by
/// the caller, which creates the ledger after the durable store is open.
pub(crate) fn reject_incomplete_layout_v2(home: &AstridHome) -> io::Result<()> {
    if home.layout_version()?.as_deref() != Some(LAYOUT_VERSION) {
        return Ok(());

View on GitHub (pinned to affd8760f4)

Solutions

1. Check the layout-version sentinel file in the Astrid home; note its value.
2. If it was written by a newer astrid version, upgrade astrid to match — downgrades across layout versions are unsupported.
3. If the sentinel is corrupt or hand-edited, restore it to the current LAYOUT_VERSION value or remove the home and let astrid initialize a fresh one after backing up data.
4. If this is a legacy home, ensure the sentinel matches astrid_core::dirs::LEGACY_LAYOUT_VERSION so the migration path is selected.

Example fix

// before (sentinel written by newer release)
$ cat ~/.astrid/layout-version
"v3"

// after: upgrade astrid, or remove the unknown sentinel/home
$ astrid --version   # confirm release matches sentinel
$ rm ~/.astrid/layout-version && astrid init  # fresh home after backup

let version = home.layout_version()?;
match version.as_deref() {
    None => { /* fresh: ok */ }
    Some(v) if v == astrid_core::dirs::LEGACY_LAYOUT_VERSION => { /* migrate first */ }
    Some(v) if v == astrid_kernel::legacy_migration_barrier::LAYOUT_VERSION => { /* v2 ok */ }
    Some(other) => eprintln!("unsupported layout version {other:?}; upgrade astrid"),
}

fn is_supported_layout(v: Option<&str>) -> bool {
    matches!(v, None | Some(x) if x == astrid_core::dirs::LEGACY_LAYOUT_VERSION || x == "2")
}

When it happens

Trigger: Any call chain reaching capture_layout_origin (e.g. via origin_is_captured_before_fresh_home_ensure in run()) where home.layout_version() returns Some(v) with v not equal to astrid_core::dirs::LEGACY_LAYOUT_VERSION and not equal to LAYOUT_VERSION.

Common situations: Pointing the Astrid home at a directory created by a newer astrid release (downgrade scenario), a hand-edited or corrupted layout sentinel file, or a foreign tool writing an unexpected sentinel value into the home directory.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• unsupported Astrid home layout version {other:?}
• unsupported Astrid home layout version {version:?}
• layout-two home contains legacy state without a completion r
• layout migration receipt does not match its intent or destin
• layout path has no existing directory ancestor: {}

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