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

unsupported Astrid home layout version {other:?}

Error message

unsupported Astrid home layout version {other:?}

What it means

begin_layout_v2_migration refuses to start a v1→v2 home-layout migration when the etc/layout-version sentinel file contains a value that is neither the current layout version nor the legacy layout version. The library only knows how to migrate from the one released legacy layout, so any other sentinel value is treated as invalid data rather than something it can upgrade.

Source

Thrown at crates/astrid-core/src/dirs_layout.rs:172

    /// the exact same source inventory, destination format, physical roots, and
    /// executable identity.
    ///
    /// # Errors
    ///
    /// Returns an error for unsupported layouts, redirected paths, invalid
    /// source content, or a prior intent for a different transaction.
    pub fn begin_layout_v2_migration(&self, target: &LayoutMigrationTarget) -> io::Result<()> {
        match self.layout_version()?.as_deref() {
            Some(LAYOUT_VERSION) => return Ok(()),
            Some(LEGACY_LAYOUT_VERSION) => {},
            None => {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    "cannot migrate an Astrid home without a layout-version sentinel",
                ));
            },
            Some(other) => {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    format!("unsupported Astrid home layout version {other:?}"),
                ));
            },
        }
        reject_automatic_windows_layout_one()?;
        self.preflight_layout_v2_paths()?;
        for path in [
            self.storage_volume_path(),
            self.legacy_storage_volume_path(),
            self.retired_root_storage_volume_path(),
        ] {
            if std::fs::symlink_metadata(&path).is_ok() {
                inventory_regular_file(&path)?;
            }
        }
        let intent = LayoutMigrationRecordV1::capture(self, target)?;
        ensure_migration_capacity(&self.var_dir(), intent.material.source.bytes)?;

View on GitHub (pinned to affd8760f4)

Solutions

  1. Read the sentinel at <home>/etc/layout-version and check its exact contents against the supported values (LAYOUT_VERSION and LEGACY_LAYOUT_VERSION from astrid-core)
  2. If the value is corrupt or hand-edited, restore it to the known legacy version value (or delete it only if the home truly has no layout yet — but note a missing sentinel raises its own error)
  3. Confirm the Astrid binary version matches the release that wrote the home; upgrade or downgrade the binary to a release that understands this sentinel value
  4. If the home was created by a future layout version, do not attempt migration; use the matching binary or a purpose-built importer

Example fix

// before: sentinel contains "layout-9" (unknown)
let v = std::fs::read_to_string("~/.astrid/etc/layout-version")?; // "layout-9"
home.begin_layout_v2_migration(&target)?; // InvalidData: unsupported version
// after
std::fs::write("~/.astrid/etc/layout-version", "1")?; // supported legacy sentinel
home.begin_layout_v2_migration(&target)?;
Defensive patterns

Strategy: validation

Validate before calling

let version = home.layout_version()?;
match version.as_deref() {
    Some(v) if v == astrid_core::LAYOUT_VERSION || v == astrid_core::LEGACY_LAYOUT_VERSION => Ok(()),
    other => Err(anyhow!("unsupported sentinel {:?}; fix etc/layout-version first", other)),
}?;

Type guard

fn is_supported_sentinel(v: &Option<String>, current: &str, legacy: &str) -> bool {
    matches!(v.as_deref(), Some(x) if x == current || x == legacy)
}

Try / catch

match home.begin_layout_v2_migration(&target) {
    Err(e) if e.kind() == std::io::ErrorKind::InvalidData
        && e.to_string().contains("unsupported Astrid home layout version") => {
        // surface the sentinel value; do not retry migration
    },
    r => r?,
}

Prevention

When it happens

Trigger: Calling AstridHome::begin_layout_v2_migration when etc/layout-version exists but holds an unrecognized string (a typo, a future layout version, a stale hand-edited sentinel, or trailing/corrupted text written by another tool).

Common situations: Hand-editing or truncating the sentinel file; running an old/newer Astrid binary against a home written by a different release; a failed partial write leaving garbage in the sentinel; copying a home directory between installs with mismatched versions.

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

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