{"record":{"id":"8ae737fe72614d46","repo":"astrid-runtime/astrid","slug":"unadmitted-entry-in-a-fresh-astrid-durable-root","errorCode":null,"errorMessage":"unadmitted entry in a fresh Astrid durable root: {}","messagePattern":"unadmitted entry in a fresh Astrid durable root: (.+?)","errorType":"validation","errorClass":"std::io::Error::InvalidData","httpStatus":null,"severity":"error","filePath":"crates/astrid-core/src/dirs.rs","lineNumber":483,"sourceCode":"                io::ErrorKind::InvalidData,\n                \"stopped Astrid durable root cannot provision runtime identity sidecars\",\n            ));\n        }\n        Ok(())\n    }\n\n    fn validate_fresh_root_entries(&self) -> io::Result<UnsentinelledRootState> {\n        let mut entries = self.root().read_dir()?.collect::<Result<Vec<_>, _>>()?;\n        entries.sort_by_key(std::fs::DirEntry::file_name);\n        if entries.len() == 1 && entries[0].file_name() == std::ffi::OsStr::new(\"keys\") {\n            self.validate_runtime_key_bootstrap(&entries[0].path())?;\n            return Ok(UnsentinelledRootState::RuntimeKeyBootstrap);\n        }\n        let mut state = UnsentinelledRootState::Empty;\n        for entry in entries {\n            let path = entry.path();\n            if entry.file_name() != std::ffi::OsStr::new(\"astrid.volume\") {\n                return Err(io::Error::new(\n                    io::ErrorKind::InvalidData,\n                    format!(\n                        \"unadmitted entry in a fresh Astrid durable root: {}\",\n                        path.display()\n                    ),\n                ));\n            }\n            let metadata = std::fs::symlink_metadata(&path)?;\n            if metadata.file_type().is_symlink() || !metadata.is_file() {\n                return Err(io::Error::new(\n                    io::ErrorKind::InvalidData,\n                    format!(\n                        \"Astrid durable media is redirected or not a regular file: {}\",\n                        path.display()\n                    ),\n                ));\n            }\n            crate::platform_fs::validate_private_file(&path)?;","sourceCodeStart":465,"sourceCodeEnd":501,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-core/src/dirs.rs#L465-L501","documentation":"Thrown by validate_fresh_root_entries in crates/astrid-core/src/dirs.rs when initializing a brand-new Astrid durable root directory that contains a filesystem entry other than the expected 'astrid.volume' sentinel file. The library enforces that a fresh root is pristine: any extra file, subdirectory, or symlink means the root was not actually empty, so initialization aborts with InvalidData rather than silently adopting a dirty directory.","triggerScenarios":"Calling ensure() or validate_runtime_identity_provisioning() on a root directory that contains entries besides astrid.volume — e.g. a leftover file from a previous install, an OS artifact like .DS_Store or desktop.ini, a log file, or a user-created file inside the root before first initialization.","commonSituations":"Users pointing the durable root at a non-empty existing directory (Documents folder, home dir, mounted volume with stray files); CI containers writing temp files into the volume path; sync tools (Dropbox/OneDrive) placing metadata files inside the root before first run.","solutions":["List the root directory and remove every entry except astrid.volume before re-running initialization.","Point the Astrid root at a genuinely empty, dedicated directory instead of a shared folder.","Exclude sync-client metadata (.DS_Store, desktop.ini, .nfs files) by disabling file-sync for the root or deleting those artifacts.","If data from a prior install exists, restore/complete that install instead of treating the root as fresh."],"exampleFix":"// before (root contaminated)\n$ ls $ASTRID_ROOT\nastrid.volume  notes.txt\nerror: unadmitted entry in a fresh Astrid durable root: notes.txt\n\n// after\n$ rm $ASTRID_ROOT/notes.txt\n$ ls $ASTRID_ROOT\nastrid.volume","handlingStrategy":"validation","validationCode":"// Rust\nfn root_is_fresh(root: &Path) -> io::Result<bool> {\n    for entry in std::fs::read_dir(root)? {\n        let entry = entry?;\n        if entry.file_name() != std::ffi::OsStr::new(\"astrid.volume\") {\n            return Ok(false); // will trigger the error\n        }\n    }\n    Ok(true)\n}","typeGuard":"fn is_valid_volume_entry(entry: &std::fs::DirEntry) -> bool {\n    entry.file_name() == std::ffi::OsStr::new(\"astrid.volume\")\n}","tryCatchPattern":"match ensure() {\n    Err(e) if e.kind() == io::ErrorKind::InvalidData\n        && e.to_string().contains(\"unadmitted entry\") => {\n        // inspect root, remove foreign entries, retry once\n    }\n    r => r?,\n}","preventionTips":["Always point the durable root at a dedicated, empty directory","Exclude the root from sync clients (Dropbox/OneDrive/iCloud)","Check read_dir contents for non-astrid.volume entries before calling ensure()","Never share the root path with other tools or scripts"],"tags":["filesystem","initialization","validation"],"backgroundTag":"invalid-state-transition","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}