Hmbown/CodeWhale · warning · std::io::Error

file appears to be binary

Error message

file appears to be binary

What it means

InvalidData ('file appears to be binary') raised by the @-mention file reader in the TUI when the read prefix buffer contains a NUL byte (0x00). NUL is the classic binary-file marker: the check runs after a partial-read truncation fix-up, so a cut mid-multibyte-sequence is repaired first and only genuine NUL content triggers this. Media files (png/jpg/...) are detected earlier by extension via is_media_path and never reach this check.

Source

Thrown at crates/tui/src/tui/file_mention.rs:1400

        .take(MAX_MENTION_FILE_BYTES + 1)
        .read_to_end(&mut buffer)?;
    let truncated = buffer.len() as u64 > MAX_MENTION_FILE_BYTES;
    if truncated {
        buffer.truncate(MAX_MENTION_FILE_BYTES as usize);
        // Round down to the nearest valid UTF-8 character boundary so a
        // multi-byte sequence (CJK, emoji, etc.) is never split at the cut point.
        // Only adjust when error_len() is None — that means truncation landed
        // mid-sequence (incomplete tail).  A Some(_) error_len means the file
        // genuinely contains invalid UTF-8 bytes; leave the buffer intact so
        // the from_utf8 call below returns the correct "file is not UTF-8" error.
        if let Err(e) = std::str::from_utf8(&buffer)
            && e.error_len().is_none()
        {
            buffer.truncate(e.valid_up_to());
        }
    }
    if buffer.contains(&0) {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            "file appears to be binary",
        ));
    }
    let text = std::str::from_utf8(&buffer)
        .map_err(|_| std::io::Error::new(std::io::ErrorKind::InvalidData, "file is not UTF-8"))?
        .to_string();
    Ok((text, truncated))
}

fn is_media_path(path: &Path) -> bool {
    let Some(ext) = path.extension().and_then(|ext| ext.to_str()) else {
        return false;
    };
    matches!(
        ext.to_ascii_lowercase().as_str(),
        "png"
            | "jpg"

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Do not @-mention the binary file; reference its path as plain text so the model can use a byte-capable tool instead
2. If you believe it is text, check for UTF-16: `file -i path` — convert with `iconv -f UTF-16 -t UTF-8`
3. Rename actual media files to their real extension so is_media_path routes them correctly

Example fix

# before
$ file -i export.dat
export.dat: application/octet-stream  # @-mention -> InvalidData: file appears to be binary

# after
$ iconv -f UTF-16LE -t UTF-8 export.dat > export.txt   # if it was UTF-16 text
# then @-mention export.txt; otherwise just type the path instead of mentioning it

// Cheap pre-check for @-mention candidates: NUL sniff on a prefix.
let mut probe = vec![0u8; 4096];
let n = std::fs::File::open(p)?.read(&mut probe)?;
if probe[..n].contains(&0) {
    return Ok(mention_as_path_only(p)); // do not attempt text ingestion
}

fn is_binary_file_error(e: &std::io::Error) -> bool {
    e.kind() == std::io::ErrorKind::InvalidData && e.to_string().contains("appears to be binary")
}

When it happens

Trigger: Using @-mention completion on a file whose first N bytes contain a NUL byte: executables, images with wrong/unknown extension, database files, serialized blobs, or UTF-16 text (whose ASCII bytes interleave with 0x00).

Common situations: Mentioning a data/image file that lacks a recognized media extension (e.g. .bin, .dat, .pickle); UTF-16 exports from Windows tools; attempting to pull a binary into the prompt as context.

Related errors

• file is not UTF-8
• unsupported locale '{other}'
• invalid locale '{value}'
• unsupported theme '{other}'
• invalid theme '{value}'

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