{"record":{"id":"7331a7403441e305","repo":"Hmbown/CodeWhale","slug":"private-sidecar-file-path-must-be-regular","errorCode":null,"errorMessage":"private sidecar file {path} must be regular","messagePattern":"private sidecar file (.+?) must be regular","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/tui/src/session_manager.rs","lineNumber":240,"sourceCode":"    if unsafe { GetFileInformationByHandle(file.as_raw_handle(), &mut info) } == 0 {\n        return Err(io::Error::last_os_error());\n    }\n    if info.nNumberOfLinks != 1 {\n        return Err(io::Error::new(\n            io::ErrorKind::InvalidData,\n            format!(\n                \"private sidecar file {} must have exactly one filesystem link\",\n                path.display()\n            ),\n        ));\n    }\n    Ok(())\n}\n\n#[cfg(all(not(unix), not(windows)))]\nfn validate_private_regular_file(file: &fs::File, path: &Path) -> io::Result<()> {\n    if !file.metadata()?.is_file() {\n        return Err(io::Error::new(\n            io::ErrorKind::InvalidData,\n            format!(\"private sidecar file {} must be regular\", path.display()),\n        ));\n    }\n    Ok(())\n}\n\n/// Persisted queued message for offline/degraded mode.\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct QueuedSessionMessage {\n    pub display: String,\n    #[serde(default)]\n    pub skill_instruction: Option<String>,\n    #[serde(default)]\n    pub skill_provenance: Option<crate::plugins::types::PluginAuthority>,\n}\n\n/// Persisted queue state for recovery after restart/crash.","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/session_manager.rs#L222-L258","documentation":"On platforms other than Unix or Windows (cfg(all(not(unix), not(windows)))), session_manager performs a minimal check that the private sidecar file is a regular file via metadata().is_file(). Directories, devices, FIFOs, or other special files at the sidecar path are rejected with InvalidData.","triggerScenarios":"Calling open_private_lock_file or open_private_read_file on a non-Unix, non-Windows target when the path exists but its metadata is_file() is false (e.g. it is a directory or special file).","commonSituations":"A directory accidentally occupies the expected sidecar filename; a custom platform/embedded filesystem returns unusual file types; tests on exotic targets point the session path at a special node.","solutions":["Check what is at the path and remove/replace the non-regular entry (e.g. `rm` a fifo/device or `rmdir` a directory).","Point the session store at a normal directory on a regular filesystem.","If you control the platform support, add an explicit validation branch for it."],"exampleFix":"// before: a directory exists where the sidecar file is expected\nls sessions/session.lock  // is a directory\n// after: remove it and let Codewhale create a real file\nrmdir sessions/session.lock","handlingStrategy":"validation","validationCode":"if !std::fs::metadata(path).map(|m| m.is_file()).unwrap_or(false) {\n    return Err(format!(\"{} must be a regular file\", path.display()));\n}","typeGuard":null,"tryCatchPattern":"match open_private_lock_file(path) {\n    Err(e) if e.kind() == std::io::ErrorKind::InvalidData => eprintln!(\"path is not a regular file: {e}\"),\n    other => other?,\n}","preventionTips":["Don't place directories or special files at sidecar paths.","Let Codewhale create sidecar files itself.","Point the session store at a normal filesystem directory."],"tags":["filesystem","io","platform"],"backgroundTag":"file-not-found","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}