{"record":{"id":"354f362166f0eecb","repo":"SixLabors/ImageSharp","slug":"the-icon-encoding-dimensions-exceed-the-source-frame","errorCode":null,"errorMessage":"The icon encoding dimensions exceed the source frame dimensions.","messagePattern":"The icon encoding dimensions exceed the source frame dimensions\\.","errorType":"exception","errorClass":"ImageFormatException","httpStatus":null,"severity":"error","filePath":"src/ImageSharp/Formats/Icon/IconEncoderCore.cs","lineNumber":123,"sourceCode":"            // The struct provider is statically dispatched, avoiding boxing and intermediary ICO/CUR metadata allocations.\n            // Only unmanaged directory data survives until backpatching; the managed color table is consumed for this frame.\n            entries[i] = provider.GetEncodingFrameMetadata(frame, out ReadOnlyMemory<Color>? colorTable);\n            int width = entries[i].Entry.Width;\n            if (width is 0)\n            {\n                width = frame.Width;\n            }\n\n            int height = entries[i].Entry.Height;\n            if (height is 0)\n            {\n                height = frame.Height;\n            }\n\n            if (width > frame.Width || height > frame.Height)\n            {\n                // EncodingWidth and EncodingHeight are public metadata, so reject a crop that exceeds the source frame here.\n                throw new ImageFormatException(\"The icon encoding dimensions exceed the source frame dimensions.\");\n            }\n\n            long imageStart = stream.Position;\n            entries[i].Entry.ImageOffset = checked((uint)(imageStart - basePosition));\n            ref EncodingFrameMetadata encodingMetadata = ref entries[i];\n            Image<TPixel>? encodingImage = null;\n\n            try\n            {\n                bool requiresCrop = width != frame.Width || height != frame.Height;\n                bool requiresIsolatedImage = encodingMetadata.Compression is IconFrameCompression.Png && image.Frames.Count > 1;\n\n                if (requiresCrop || requiresIsolatedImage)\n                {\n                    // PNG accepts Image rather than ImageFrame, and ANI variants may occupy only part of their common canvas.\n                    // Allocate only for those cases; full-sized BMP frames can be encoded directly from their existing storage.\n                    ImageMetadata? metadata = this.encoder.SkipMetadata || encodingMetadata.Compression is not IconFrameCompression.Png ? null : image.Metadata.DeepClone();\n                    encodingImage = new Image<TPixel>(image.Configuration, width, height, metadata);","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/SixLabors/ImageSharp/blob/59ce6af6fc29027cda277ef62d4d1694a8acce91/src/ImageSharp/Formats/Icon/IconEncoderCore.cs#L105-L141","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nmetadata.EncodingWidth = 256;\nmetadata.EncodingHeight = 256; // frame is only 64x64\nimage.Save(\"out.ico\");\n// after\nmetadata.EncodingWidth = Math.Min(256, metadata.Width);\nmetadata.EncodingHeight = Math.Min(256, metadata.Height);\nimage.Save(\"out.ico\");","handlingStrategy":"validation","validationCode":"// clamp encoding metadata to the actual frame size before saving\nforeach (var f in image.Frames)\n{\n    var md = f.Metadata.GetIcoMetadata();\n    md.EncodingWidth = Math.Min(md.EncodingWidth, f.Width);\n    md.EncodingHeight = Math.Min(md.EncodingHeight, f.Height);\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    image.Save(\"out.ico\", new IcoEncoder());\n}\ncatch (ImageFormatException ex)\n{\n    // encoding dimensions exceed source frame\n    throw new InvalidOperationException(\"Fix EncodingWidth/EncodingHeight metadata\", ex);\n}","preventionTips":["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"],"tags":["icon","ico","encoder","metadata-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"59ce6af6fc29027cda277ef62d4d1694a8acce91","analyzedAt":"2026-09-13T18:34:59.331Z","contentChangedAt":"2026-09-13T18:34:59.331Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}