{"record":{"id":"cf23b1a2f6ea7ed4","repo":"astrid-runtime/astrid","slug":"unsupported-astrid-home-layout-version-version","errorCode":null,"errorMessage":"unsupported Astrid home layout version {version:?}","messagePattern":"unsupported Astrid home layout version (.+?)","errorType":"validation","errorClass":"std::io::Error::InvalidData","httpStatus":null,"severity":"error","filePath":"crates/astrid-core/src/dirs.rs","lineNumber":344,"sourceCode":"    /// Fresh initialization leaves only the private root for the storage layer\n    /// to fill with `astrid.volume`. The sole pre-volume exception is the\n    /// private runtime-key bootstrap that storage ingests on first open.\n    /// Released homes retain their historical directories and sentinel as\n    /// one-time migration inputs until verified cutover. Running projections\n    /// are created later from mounted volume state, never by this admission\n    /// boundary.\n    ///\n    /// # Errors\n    ///\n    /// Returns an error if directory creation or permission setting fails.\n    pub fn ensure(&self) -> io::Result<()> {\n        self.validate_run_dir()?;\n        let existing_layout = self.layout_version()?;\n        if let Some(version) = existing_layout.as_deref()\n            && version != LEGACY_LAYOUT_VERSION\n            && version != LAYOUT_VERSION\n        {\n            return Err(io::Error::new(\n                io::ErrorKind::InvalidData,\n                format!(\"unsupported Astrid home layout version {version:?}\"),\n            ));\n        }\n        if existing_layout.is_none() {\n            match std::fs::symlink_metadata(self.root()) {\n                Ok(metadata) if metadata.file_type().is_symlink() || !metadata.is_dir() => {\n                    return Err(io::Error::new(\n                        io::ErrorKind::InvalidData,\n                        format!(\n                            \"Astrid home without a layout sentinel is redirected or not a directory: {}\",\n                            self.root().display()\n                        ),\n                    ));\n                },\n                Ok(_) => {},\n                Err(error) if error.kind() == io::ErrorKind::NotFound => {},\n                Err(error) => return Err(error),","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-core/src/dirs.rs#L326-L362","documentation":"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.","triggerScenarios":"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.","commonSituations":"Downgrading the Astrid binary after a layout version bump, or manually editing/creating the sentinel file with a wrong value.","solutions":["Upgrade Astrid to a version that supports the recorded layout version","Back up and re-initialize the home directory if a downgrade is required","Fix or remove the sentinel file if it was edited by mistake (only when certain)"],"exampleFix":"// before: sentinel written by newer version\ncat $ASTRID_HOME/.layout  # e.g. \"v3\" while binary supports v1/v2\n// after: upgrade the binary\nastrid --version  # install version matching the layout sentinel","handlingStrategy":"try-catch","validationCode":"let sentinel = std::fs::read_to_string(astrid_home.join(\".layout\")).ok();\nif let Some(v) = sentinel.as_deref() {\n    assert!(v == LEGACY_LAYOUT_VERSION || v == LAYOUT_VERSION, \"unsupported layout {v}\");\n}","typeGuard":null,"tryCatchPattern":"match dirs.ensure() {\n    Err(e) if e.kind() == io::ErrorKind::InvalidData && e.to_string().contains(\"layout version\") => {\n        // upgrade binary or re-init home\n    },\n    other => other?,\n}","preventionTips":["Keep the Astrid binary version aligned with the initialized home","Read release notes for layout version bumps before downgrading","Back up the home before manual sentinel edits"],"tags":["migration","versioning","layout"],"backgroundTag":"unsupported-config-value","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}