Hmbown/CodeWhale · error · InvalidData

private sidecar file

Error message

private sidecar file {} must be a non-reparse regular file

What it means

On Windows, validate_private_regular_file rejects sidecar files that are not regular files or carry the FILE_ATTRIBUTE_REPARSE_POINT flag (symlinks, junctions, mounts). Such files could redirect the private lock/read target elsewhere, so the manager throws InvalidData.

Solutions

Remove the symlink/junction and restore a real directory/file at the session state path
Exclude the sessions directory from OneDrive/sync placeholders (make files locally available)
Copy the real directory contents back if state was moved to a junction location

Example fix

// diagnose
fsutil reparsepoint query <path>
// fix (PowerShell)
Remove-Item <junction-path> -Force
Move-Item <real-path> <original-path>

Defensive patterns

Strategy: validation

Validate before calling

let md = std::fs::metadata(&path)?;
if !md.is_file() || md.file_attributes() & 0x400 != 0 { return Err("sidecar must be a non-reparse regular file"); }

Try / catch

match manager.open_session() {
    Err(e) if e.to_string().contains("non-reparse") => relocate_state_to_real_dir(),
    other => other,
}

Prevention

Do not redirect session state dirs via symlinks/junctions
Exclude state dirs from OneDrive/sync placeholders
Keep session state on a local NTFS volume

When it happens

Trigger: open_private_lock_file / open_private_read_file opens a path whose Windows metadata reports a reparse point or a non-regular file attribute.

Common situations: Users substituting the session state directory with a symlink or junction (e.g. moving state to another drive via junction), OneDrive/Dropbox placeholder files, or tampering.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/7765bacf3387a670. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/session_manager.rs:212

                "private sidecar file {} must be one regular filesystem link",
                path.display()
            ),
        ));
    }
    Ok(())
}

#[cfg(windows)]
fn validate_private_regular_file(file: &fs::File, path: &Path) -> io::Result<()> {
    use std::os::windows::fs::MetadataExt as _;
    use std::os::windows::io::AsRawHandle as _;
    use windows_sys::Win32::Storage::FileSystem::{
        BY_HANDLE_FILE_INFORMATION, FILE_ATTRIBUTE_REPARSE_POINT, GetFileInformationByHandle,
    };

    let metadata = file.metadata()?;
    if !metadata.is_file() || metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            format!(
                "private sidecar file {} must be a non-reparse regular file",
                path.display()
            ),
        ));
    }
    let mut info = BY_HANDLE_FILE_INFORMATION::default();
    // SAFETY: `file` keeps the handle valid and `info` is writable for the call.
    if unsafe { GetFileInformationByHandle(file.as_raw_handle(), &mut info) } == 0 {
        return Err(io::Error::last_os_error());
    }
    if info.nNumberOfLinks != 1 {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            format!(
                "private sidecar file {} must have exactly one filesystem link",
                path.display()

View on GitHub (pinned to 433685b202)