{"record":{"id":"d79222601977d474","repo":"Hmbown/CodeWhale","slug":"private-sidecar-file-must-have-exactly-one-filesystem-link","errorCode":null,"errorMessage":"private sidecar file {} must have exactly one filesystem link","messagePattern":"private sidecar file (.+?) must have exactly one filesystem link","errorType":"validation","errorClass":"InvalidData","httpStatus":null,"severity":"error","filePath":"crates/tui/src/session_manager.rs","lineNumber":226,"sourceCode":"    };\n\n    let metadata = file.metadata()?;\n    if !metadata.is_file() || metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {\n        return Err(io::Error::new(\n            io::ErrorKind::InvalidData,\n            format!(\n                \"private sidecar file {} must be a non-reparse regular file\",\n                path.display()\n            ),\n        ));\n    }\n    let mut info = BY_HANDLE_FILE_INFORMATION::default();\n    // SAFETY: `file` keeps the handle valid and `info` is writable for the call.\n    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    }","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/crates/tui/src/session_manager.rs#L208-L244","documentation":"On Windows, after checking file type and reparse attributes, validate_private_regular_file also requires nNumberOfLinks == 1 via GetFileInformationByHandle. Multiple hard links mean the sidecar is shared, breaking the private-file guarantee, so the manager throws InvalidData.","triggerScenarios":"open_private_lock_file / open_private_read_file succeeds in opening the file, but BY_HANDLE_FILE_INFORMATION reports nNumberOfLinks != 1 (file hard-linked elsewhere).","commonSituations":"Hard-linking the lock file via mklink /H or backup tools that create hard links; sharing a profile directory via hard links instead of copies.","solutions":["Delete the extra hard links (or the sidecar itself; the manager recreates it)","Check with fsutil hardlink list <file> where the other links live","Stop tools that hard-link session state (backup dedup, link shells extension)"],"exampleFix":"// diagnose\nfsutil hardlink list <sidecar-path>\n// fix\nrm <sidecar-path>            # recreate clean sidecar\nCopy-Item <source> <dest>    # use copies, not hard links, for state sharing","handlingStrategy":"validation","validationCode":"// Windows: check hard-link count before opening\nlet links = std::fs::metadata(&path)?.file_attributes(); // full check needs GetFileInformationByHandle; pre-check existence + regular","typeGuard":null,"tryCatchPattern":"match manager.open_session() {\n    Err(e) if e.to_string().contains(\"exactly one filesystem link\") => recreate_sidecar(),\n    other => other,\n}","preventionTips":["Avoid dedup/backup tools that hard-link state files","Run `fsutil hardlink list` when the error appears to find culprits","Share state by copying, never by hard links"],"tags":["rust","windows","filesystem","hardlink","security"],"backgroundTag":"invalid-argument-value","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-22T01:17:13.364Z"}