SixLabors/ImageSharp · error · InvalidImageContentException

PNG Image must contain a header chunk and it must be…

Error message

PNG Image must contain a header chunk and it must be located before any other chunks.

What it means

Thrown when the decoder never encounters a PNG IHDR (header) chunk, or encounters it after other chunks. The IHDR chunk is mandatory and per the PNG specification must be the first chunk in the file; without it the decoder cannot determine dimensions, bit depth, or color type.

Solutions

1. Check that the file begins with the PNG signature (137 80 78 71 13 10 26 10) followed immediately by an IHDR chunk.
2. Re-export or re-save the image from the original source or a different encoder.
3. If you generate PNGs programmatically, write IHDR as the first chunk after the signature.
4. Catch InvalidImageContentException to detect malformed uploads.

Example fix

// before (custom writer)
WriteChunk(stream, "gAMA", ...);
WriteChunk(stream, "IHDR", header);
// after
WriteChunk(stream, "IHDR", header);
WriteChunk(stream, "gAMA", ...);

static bool HasIhdrFirst(byte[] png) =>
    png.Length >= 16 &&
    png.AsSpan(0, 8).SequenceEqual(stackalloc byte[] { 137, 80, 78, 71, 13, 10, 26, 10 }) &&
    png[12] == (byte)'I' && png[13] == (byte)'H' && png[14] == (byte)'D' && png[15] == (byte)'R';

try
{
    using var image = Image.Load(stream);
}
catch (InvalidImageContentException ex) when (ex.Message.Contains("header chunk"))
{
    // missing/misordered IHDR — reject the file
}

When it happens

Trigger: Decoding a stream whose first chunk is not IHDR (e.g. missing signature/header, data starting with other chunk types), or a file where IHDR was stripped or relocated after other chunks.

Common situations: Truncated downloads that cut off the header, custom chunk writers emitting ancillary chunks before IHDR, files that are actually APNG/Cairo ' png' variants or other formats mislabeled as PNG.

Related errors

• PNG Image does not contain a data chunk.
• Invalid or unsupported color type. Was
• Invalid or unsupported bit depth. Was
• Invalid filter method. Expected 0. Was
• Invalid interlace method. Expected 'None' or 'Adam7'. Was

AI-assisted analysis of SixLabors/ImageSharp@59ce6af6fc (2026-09-13). Data as JSON: /api/errors/3035b818040e2802. Report an issue: GitHub.

Appendix: source

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

// Copyright (c) Six Labors.
// Licensed under the Six Labors Split License.

using System.Diagnostics.CodeAnalysis;
using System.Runtime.CompilerServices;

namespace SixLabors.ImageSharp.Formats.Png;

internal static class PngThrowHelper
{
    [DoesNotReturn]
    public static void ThrowInvalidImageContentException(string errorMessage) => throw new InvalidImageContentException(errorMessage);

    [DoesNotReturn]
    public static void ThrowInvalidHeader() => throw new InvalidImageContentException("PNG Image must contain a header chunk and it must be located before any other chunks.");

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

    [DoesNotReturn]
    public static void ThrowMissingDefaultData() => throw new InvalidImageContentException("APNG Image does not contain a default data chunk.");

    [DoesNotReturn]
    public static void ThrowInvalidAnimationControl() => throw new InvalidImageContentException("APNG Image must contain a acTL chunk and it must be located before any IDAT and fdAT chunks.");

    [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.");

View on GitHub (pinned to 59ce6af6fc)