What causes "Invalid {name}. {message}. Was '{value}'." in SixLabors/ImageSharp?

Inspect the exception message: it names the invalid parameter (e.g. Width, XOffset) and its value; verify the source PNG file's chunk data with a PNG inspector (pngcheck).

SixLabors/ImageSharp · error · NotSupportedException

Invalid . . Was ' '.

Error message

Invalid {name}. {message}. Was '{value}'.

What it means

PngThrowHelper.ThrowInvalidParameter throws NotSupportedException with 'Invalid {name}. {message}. Was {value}.' when a decoded PNG chunk carries a parameter value that is structurally invalid. It is thrown during PNG decode when header/frame-control values violate PNG invariants (e.g. zero dimensions, offsets exceeding image width). The exception name embeds the caller's argument expression and offending value, so it pinpoints exactly which decoded field was bad.

Solutions

Inspect the exception message: it names the invalid parameter (e.g. Width, XOffset) and its value; verify the source PNG file's chunk data with a PNG inspector (pngcheck).
Re-export or re-encode the image with a conformant PNG/APNG encoder to repair the malformed chunk.
If the file comes from an untrusted source, validate/reject it before decode; treat NotSupportedException as 'malformed input', not a library bug.
Upgrade SixLabors.ImageSharp in case newer decoders accept additional edge-case values.

Example fix

// before
Image.Load("animation.apng"); // throws NotSupportedException: Invalid XOffset... Was '2000'
// after
try
{
    Image.Load("animation.apng");
}
catch (NotSupportedException ex)
{
    // log and reject the malformed PNG
    Console.WriteLine($"Malformed PNG chunk parameter: {ex.Message}");
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Cannot inspect PNG chunks without parsing; at minimum sanity-check the file.
byte[] hdr = new byte[33];
using (var fs = File.OpenRead(path))
    if (fs.Read(hdr, 0, hdr.Length) < hdr.Length) throw new InvalidDataException("Too short for PNG header chunks.");
bool isPng = hdr.AsSpan(0, 8).SequenceEqual(new byte[]{137,80,78,71,13,10,26,10});

Try / catch

try { using var img = Image.Load(path); }
catch (NotSupportedException ex) { LogError(ex, "Malformed PNG chunk parameter; reject file."); }

Prevention

Treat NotSupportedException during PNG decode as malformed input, not a library defect.
Validate untrusted images with pngcheck before processing.
Re-encode animations with a conformant APNG encoder.
Log the exception message verbatim — it names the bad field and value.

When it happens

Trigger: Decoding a PNG whose PngFrameControl has Width <= 0 (FrameControl.cs:107), Height <= 0 (line 112), or XOffset + Width exceeding PngHeader.Width (line 117); these call PngThrowHelper.ThrowInvalidParameter with the offending field value.

Common situations: Processing truncated, hand-crafted, or corrupted APNG files; fuzzer-generated PNGs; images produced by encoders that write malformed fcTL/fdAT chunk sequences.

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 SixLabors/ImageSharp@59ce6af6fc (2026-09-13). Data as JSON: /api/errors/760d023bb5dbdf23. Report an issue: GitHub.

Appendix: source

Thrown at src/ImageSharp/Formats/Png/PngThrowHelper.cs:43

    [DoesNotReturn]
    public static void ThrowMissingFrameControl() => throw new InvalidImageContentException("One of APNG Image's frames do not have a frame control chunk.");

    [DoesNotReturn]
    public static void ThrowMissingPalette() => throw new InvalidImageContentException("PNG Image does not contain a palette chunk.");

    [DoesNotReturn]
    public static void ThrowInvalidChunkType() => throw new InvalidImageContentException("Invalid PNG data.");

    [DoesNotReturn]
    public static void ThrowInvalidChunkType(string message) => throw new InvalidImageContentException(message);

    [DoesNotReturn]
    public static void ThrowInvalidChunkCrc(string chunkTypeName) => throw new InvalidImageContentException($"CRC Error. PNG {chunkTypeName} chunk is corrupt!");

    [DoesNotReturn]
    public static void ThrowInvalidParameter(object value, string message, [CallerArgumentExpression(nameof(value))] string name = "")
        => throw new NotSupportedException($"Invalid {name}. {message}. Was '{value}'.");

    [DoesNotReturn]
    public static void ThrowInvalidParameter(object value1, object value2, string message, [CallerArgumentExpression(nameof(value1))] string name1 = "", [CallerArgumentExpression(nameof(value2))] string name2 = "")
        => throw new NotSupportedException($"Invalid {name1} or {name2}. {message}. Was '{value1}' and '{value2}'.");

    [DoesNotReturn]
    public static void ThrowNotSupportedColor() => throw new NotSupportedException("Unsupported PNG color type.");

    [DoesNotReturn]
    public static void ThrowUnknownFilter() => throw new InvalidImageContentException("Unknown filter type.");
}

View on GitHub (pinned to 59ce6af6fc)