{"record":{"id":"5ba0a9fd03ed07fe","repo":"astrid-runtime/astrid","slug":"astrid-volume-is-not-a-regular-file","errorCode":null,"errorMessage":"Astrid volume is not a regular file","messagePattern":"Astrid volume is not a regular file","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage/src/volume/hosted/open.rs","lineNumber":91,"sourceCode":"        let swap_guard = open_lock.lock();\n        reclaim::recover_artifacts(&path)?;\n        let mut options = OpenOptions::new();\n        options.read(true).write(true).create(true);\n        #[cfg(unix)]\n        {\n            use std::os::unix::fs::OpenOptionsExt as _;\n            options.mode(0o600).custom_flags(libc::O_NOFOLLOW);\n        }\n        #[cfg(windows)]\n        {\n            use std::os::windows::fs::OpenOptionsExt as _;\n            use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_OPEN_REPARSE_POINT;\n            options.custom_flags(FILE_FLAG_OPEN_REPARSE_POINT);\n        }\n        let mut file = options.open(&path)?;\n        let metadata = file.metadata()?;\n        if !metadata.is_file() {\n            return Err(io::Error::new(\n                io::ErrorKind::InvalidData,\n                \"Astrid volume is not a regular file\",\n            ));\n        }\n        file.try_lock_exclusive().map_err(|error| {\n            if error.kind() == io::ErrorKind::WouldBlock {\n                io::Error::new(io::ErrorKind::WouldBlock, \"Astrid volume is already open\")\n            } else {\n                error\n            }\n        })?;\n        let length = file.metadata()?.len();\n        if length == 0 {\n            file.write_all(&VOLUME_MAGIC)?;\n            file.sync_all()?;\n        } else {\n            let mut magic = [0_u8; VOLUME_MAGIC.len()];\n            file.read_exact(&mut magic)?;","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage/src/volume/hosted/open.rs#L73-L109","documentation":"After opening the volume file, open() stats it and requires metadata.is_file(). Paths that resolve to directories, FIFOs, devices, or reparse-point/symlink targets that are not regular files are rejected with InvalidData. This protects the locking and fixed-offset I/O model, which only works on regular files.","triggerScenarios":"Opening a volume path that is a directory; opening a special file (fifo/socket/device); opening through a symlink or Windows reparse point that resolves to a non-regular target (note FILE_FLAG_OPEN_REPARSE_POINT is used on Windows).","commonSituations":"Misconfiguration pointing VOLUME_PATH at a directory or a mount point; a broken provisioning step replaced the volume file with a symlink to something else; tmpfs/pipe-based test fixtures.","solutions":["Verify the path points at a regular file: run `file <path>` or check it is not a directory/symlink.","Fix the configured volume path to reference the actual volume file.","If a symlink is intentional, point the config at the real regular-file target.","Recreate the volume with the library's create path if the file was replaced by something else."],"exampleFix":"// before\nlet volume = HostedVolume::open(\"/data/volumes\")?; // a directory\n// after\nlet volume = HostedVolume::open(\"/data/volumes/volume.astrid\")?;","handlingStrategy":"validation","validationCode":"fn is_regular_file(path: &Path) -> std::io::Result<bool> {\n    Ok(std::fs::metadata(path)?.is_file())\n}","typeGuard":null,"tryCatchPattern":"match HostedVolume::open(&path) {\n    Err(e) if e.kind() == io::ErrorKind::InvalidData\n        && e.to_string().contains(\"not a regular file\") => {\n        eprintln!(\"{path:?} is not a regular file; fix VOLUME_PATH\");\n    }\n    other => { /* ... */ }\n}","preventionTips":["Check the target with fs::metadata(path).is_file() before opening.","Do not point volume config at directories, pipes, or device nodes.","Resolve symlinks intentionally and verify the target is a regular file."],"tags":["storage","filesystem","validation","path"],"backgroundTag":"incompatible-source-type","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"}