Hmbown/CodeWhale · error

must be a regular file

Error message

must be a regular file

What it means

Fallback-platform guard in runtime_store_file_identity (cfg(all(not(unix), not(windows)))): on an OS with no dev/ino or file-index APIs, the only check available is that the handle refers to a regular file. It fires when the opened store/event path is a directory, special file, or similar; identity is then degenerate (0, 0).

Source

Thrown at crates/tui/src/runtime_threads.rs:8990

    let metadata = file.metadata()?;
    let safe = metadata.is_file() && metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT == 0;
    anyhow::ensure!(safe, "not a regular non-reparse file");
    let mut info = BY_HANDLE_FILE_INFORMATION::default();
    // SAFETY: the handle and writable output remain valid for the call.
    if unsafe { GetFileInformationByHandle(file.as_raw_handle(), &mut info) } == 0 {
        return Err(std::io::Error::last_os_error()).context("Inspect Runtime store file identity");
    }
    anyhow::ensure!(info.nNumberOfLinks == 1, "has multiple filesystem links");
    Ok((
        u64::from(info.dwVolumeSerialNumber),
        (u64::from(info.nFileIndexHigh) << 32) | u64::from(info.nFileIndexLow),
    ))
}

#[cfg(all(not(unix), not(windows)))]
fn runtime_store_file_identity(file: &File) -> Result<(u64, u64)> {
    anyhow::ensure!(file.metadata()?.is_file(), "must be a regular file");
    Ok((0, 0))
}

fn validate_same_runtime_store_file_handles(
    first: &File,
    second: &File,
    path: &Path,
) -> Result<()> {
    let first = runtime_store_file_identity(first)?;
    let second = runtime_store_file_identity(second)?;
    anyhow::ensure!(
        first == second,
        "Runtime event file changed: {}",
        path.display()
    );
    Ok(())
}

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Verify the store path is a plain file, not a directory or device node
2. Point the runtime store at a regular file on a supported filesystem
3. On production platforms use the Unix/Windows builds, which do full identity checks

When it happens

Trigger: Thrown at crates/tui/src/runtime_threads.rs:8990 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/de7e91665ddd4c81. Report an issue: GitHub.