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

unsupported Astrid home layout version {version:?}

Error message

unsupported Astrid home layout version {version:?}

What it means

Thrown by AstridDirs::ensure when the home directory contains a layout sentinel recording a version that is neither the legacy nor the current layout version. The library refuses to operate on home directories created by unknown/newer versions to avoid corrupting them.

Source

Thrown at crates/astrid-core/src/dirs.rs:344

    /// Fresh initialization leaves only the private root for the storage layer
    /// to fill with `astrid.volume`. The sole pre-volume exception is the
    /// private runtime-key bootstrap that storage ingests on first open.
    /// Released homes retain their historical directories and sentinel as
    /// one-time migration inputs until verified cutover. Running projections
    /// are created later from mounted volume state, never by this admission
    /// boundary.
    ///
    /// # Errors
    ///
    /// Returns an error if directory creation or permission setting fails.
    pub fn ensure(&self) -> io::Result<()> {
        self.validate_run_dir()?;
        let existing_layout = self.layout_version()?;
        if let Some(version) = existing_layout.as_deref()
            && version != LEGACY_LAYOUT_VERSION
            && version != LAYOUT_VERSION
        {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!("unsupported Astrid home layout version {version:?}"),
            ));
        }
        if existing_layout.is_none() {
            match std::fs::symlink_metadata(self.root()) {
                Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {
                    return Err(io::Error::new(
                        io::ErrorKind::InvalidData,
                        format!(
                            "Astrid home without a layout sentinel is redirected or not a directory: {}",
                            self.root().display()
                        ),
                    ));
                },
                Ok(_) => {},
                Err(error) if error.kind() == io::ErrorKind::NotFound => {},
                Err(error) => return Err(error),

View on GitHub (pinned to affd8760f4)

Solutions

  1. Upgrade Astrid to a version that supports the recorded layout version
  2. Back up and re-initialize the home directory if a downgrade is required
  3. Fix or remove the sentinel file if it was edited by mistake (only when certain)

Example fix

// before: sentinel written by newer version
cat $ASTRID_HOME/.layout  # e.g. "v3" while binary supports v1/v2
// after: upgrade the binary
astrid --version  # install version matching the layout sentinel
Defensive patterns

Strategy: try-catch

Validate before calling

let sentinel = std::fs::read_to_string(astrid_home.join(".layout")).ok();
if let Some(v) = sentinel.as_deref() {
    assert!(v == LEGACY_LAYOUT_VERSION || v == LAYOUT_VERSION, "unsupported layout {v}");
}

Try / catch

match dirs.ensure() {
    Err(e) if e.kind() == io::ErrorKind::InvalidData && e.to_string().contains("layout version") => {
        // upgrade binary or re-init home
    },
    other => other?,
}

Prevention

When it happens

Trigger: Calling ensure (directly or via prepare/signing flows) on a home whose layout sentinel file holds an unrecognized version string, e.g. a directory initialized by a newer Astrid release.

Common situations: Downgrading the Astrid binary after a layout version bump, or manually editing/creating the sentinel file with a wrong value.

Related errors

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