iOfficeAI/OfficeCLI · error · ArgumentException

Image file '{path}' does not appear to be a valid {ext} file

Error message

Image file '{path}' does not appear to be a valid {ext} file (magic bytes mismatch).

What it means

Thrown by ImageSource.ResolveFile when a raster image file (png, jpg, gif, bmp, tiff) fails magic-byte sniffing entirely — TrySniffContentType returns false, meaning the first 4 bytes do not match any known image signature. Unlike the extension/content-type mismatch (which recognizes a valid image of the wrong type), this error means the file does not start with any recognizable image header at all. It indicates the file is corrupted, truncated, or is not actually an image.

Source

Thrown at src/officecli/Core/ImageSource.cs:91

        // Magic-byte validation for raster formats. SVG (XML) / EMF / WMF are
        // intentionally skipped: SVG has no fixed magic, EMF/WMF have weaker
        // headers and TrySniffContentType doesn't cover them. Only validate
        // formats whose first 4 bytes are stable (png/jpg/gif/bmp/tiff).
        var rasterExts = new[] { "png", "jpg", "jpeg", "gif", "bmp", "tif", "tiff" };
        if (rasterExts.Contains(ext))
        {
            var bytes = File.ReadAllBytes(path);
            if (TrySniffContentType(bytes, out var sniffed))
            {
                if (!IsCompatible(sniffed, contentType))
                    throw new ArgumentException(
                        $"Image file '{path}' has extension .{ext} but magic bytes indicate {ContentTypeName(sniffed)}. " +
                        "Rename or convert the file.");
            }
            else
            {
                throw new ArgumentException(
                    $"Image file '{path}' does not appear to be a valid {ext} file (magic bytes mismatch).");
            }
            return (new MemoryStream(bytes, writable: false), contentType);
        }

        return (File.OpenRead(path), contentType);
    }

    private static bool IsCompatible(PartTypeInfo sniffed, PartTypeInfo declared)
    {
        if (sniffed == declared) return true;
        // jpg/jpeg are the same PartTypeInfo so this collapses naturally.
        return false;
    }

    private static string ContentTypeName(PartTypeInfo type)
    {
        if (type == ImagePartType.Png) return "PNG";

View on GitHub (pinned to 1ced45e900)

Solutions

Re-download or re-generate the image file from its original source.
Verify the file is a valid image using an external tool ('file broken.png' or opening it in an image viewer).
If the file has a valid image embedded after a header/preamble, strip the prefix and retry.
If the file is genuinely not an image, supply the correct image file.

Example fix

// before — corrupt or non-image file
add image src='/tmp/corrupt.png' path='/body'

// after — supply a valid image file
// re-export or re-download the image, verify:
//   $ file /tmp/logo.png → 'PNG image data'
add image src='/tmp/logo.png' path='/body'

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check: verify the file is a valid image by reading its header
byte[] header = new byte[8];
using (var fs = File.OpenRead(path))
{
    if (fs.Read(header, 0, 8) < 4)
    {
        Console.Error.WriteLine($"File too small or empty to be a valid image: {path}");
        return;
    }
}
bool isKnownImage = (header[0]==0x89 && header[1]==0x50) // PNG
    || (header[0]==0xFF && header[1]==0xD8)               // JPEG
    || (header[0]==0x47 && header[1]==0x49)               // GIF
    || (header[0]==0x42 && header[1]==0x4D);               // BMP
if (!isKnownImage)
    Console.Error.WriteLine($"File does not have a recognized image header: {path}");

Try / catch

try
{
    var (stream, contentType) = ImageSource.Resolve(path);
}
catch (ArgumentException ex) when (ex.Message.Contains("magic bytes mismatch"))
{
    // File is corrupt or not an image — re-download or re-generate
}

Prevention

Verify downloaded images with an external tool ('file image.png') before embedding.
Check file sizes: a 0-byte or suspiciously small file is likely corrupt.
In download pipelines, validate HTTP response integrity (checksums, Content-Length match) before writing to disk.

When it happens

Trigger: Passing a file with a raster extension (e.g. 'broken.png') whose content does not begin with any known magic byte sequence. This includes: truncated downloads, text files renamed to .png, encrypted/encoded payloads, zero-byte files that somehow passed File.Exists, or files with prepended garbage before the actual image header.

Common situations: A download was interrupted leaving a partial file. A build pipeline produced a corrupt image artifact. A file was corrupted in transit or storage. The path points to a text/log file that was accidentally given an image extension.

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/3da40ab4afaee755. Report an issue: GitHub.