SixLabors/ImageSharp · error · ImageFormatException

The icon encoding dimensions exceed the source frame…

Error message

The icon encoding dimensions exceed the source frame dimensions.

What it means

Thrown during icon encoding when the public EncodingWidth/EncodingHeight metadata for a frame specifies a crop larger than the actual source frame dimensions. Because these are caller-provided public metadata values, SixLabors.ImageSharp rejects the request with ImageFormatException rather than silently cropping or scaling.

Solutions

Clamp EncodingWidth/EncodingHeight to at most frame.Width/frame.Height before saving
Derive encoding dimensions from the actual frame metadata instead of hardcoding
Set EncodingWidth/EncodingHeight to 0 to use the frame's natural size
Catch ImageFormatException to surface which frame's metadata is inconsistent

Example fix

// before
metadata.EncodingWidth = 256;
metadata.EncodingHeight = 256; // frame is only 64x64
image.Save("out.ico");
// after
metadata.EncodingWidth = Math.Min(256, metadata.Width);
metadata.EncodingHeight = Math.Min(256, metadata.Height);
image.Save("out.ico");

Defensive patterns

Strategy: validation

Validate before calling

// clamp encoding metadata to the actual frame size before saving
foreach (var f in image.Frames)
{
    var md = f.Metadata.GetIcoMetadata();
    md.EncodingWidth = Math.Min(md.EncodingWidth, f.Width);
    md.EncodingHeight = Math.Min(md.EncodingHeight, f.Height);
}

Try / catch

try
{
    image.Save("out.ico", new IcoEncoder());
}
catch (ImageFormatException ex)
{
    // encoding dimensions exceed source frame
    throw new InvalidOperationException("Fix EncodingWidth/EncodingHeight metadata", ex);
}

Prevention

Set EncodingWidth/EncodingHeight = 0 to default to frame size
Never copy encoding metadata between differently sized images
Derive encoding sizes from frame metadata, not constants

When it happens

Trigger: Setting EncodingWidth/EncodingHeight (IcoEncodingFrameMetadata) greater than the frame's Width/Height and then encoding to ICO/CUR, e.g. metadata copied from a different larger image or hardcoded values.

Common situations: Copying encoding metadata between images of different sizes; hardcoding common icon sizes (256x256) while the source frame is smaller; off-by-scale logic in icon generation pipelines.

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/354f362166f0eecb. Report an issue: GitHub.

Appendix: source

Thrown at src/ImageSharp/Formats/Icon/IconEncoderCore.cs:123

            // The struct provider is statically dispatched, avoiding boxing and intermediary ICO/CUR metadata allocations.
            // Only unmanaged directory data survives until backpatching; the managed color table is consumed for this frame.
            entries[i] = provider.GetEncodingFrameMetadata(frame, out ReadOnlyMemory<Color>? colorTable);
            int width = entries[i].Entry.Width;
            if (width is 0)
            {
                width = frame.Width;
            }

            int height = entries[i].Entry.Height;
            if (height is 0)
            {
                height = frame.Height;
            }

            if (width > frame.Width || height > frame.Height)
            {
                // EncodingWidth and EncodingHeight are public metadata, so reject a crop that exceeds the source frame here.
                throw new ImageFormatException("The icon encoding dimensions exceed the source frame dimensions.");
            }

            long imageStart = stream.Position;
            entries[i].Entry.ImageOffset = checked((uint)(imageStart - basePosition));
            ref EncodingFrameMetadata encodingMetadata = ref entries[i];
            Image<TPixel>? encodingImage = null;

            try
            {
                bool requiresCrop = width != frame.Width || height != frame.Height;
                bool requiresIsolatedImage = encodingMetadata.Compression is IconFrameCompression.Png && image.Frames.Count > 1;

                if (requiresCrop || requiresIsolatedImage)
                {
                    // PNG accepts Image rather than ImageFrame, and ANI variants may occupy only part of their common canvas.
                    // Allocate only for those cases; full-sized BMP frames can be encoded directly from their existing storage.
                    ImageMetadata? metadata = this.encoder.SkipMetadata || encodingMetadata.Compression is not IconFrameCompression.Png ? null : image.Metadata.DeepClone();
                    encodingImage = new Image<TPixel>(image.Configuration, width, height, metadata);

View on GitHub (pinned to 59ce6af6fc)