What causes "The provided frames must be of the same size." in SixLabors/ImageSharp?

Normalize all frames to one size (clone with resize) before constructing the image

SixLabors/ImageSharp · error · ArgumentException

The provided frames must be of the same size.

Error message

The provided frames must be of the same size.

What it means

Image<TPixel>.ValidateFramesAndGetSize requires all frames passed to the image constructor to share the same Size as the first frame. Multi-size frame lists cannot back a single Image, so a mismatched list is rejected with ArgumentException.

Solutions

Normalize all frames to one size (clone with resize) before constructing the image
Build separate images per size group instead of one combined image
Verify f.Size equals the root frame size before calling the constructor

Example fix

// before
var image = new Image<Rgba32>(config, frames);
// after
Size size = frames[0].Size;
frames = frames.Select(f => f.Size == size ? f : f.Clone(config, size)).ToList();
var image = new Image<Rgba32>(config, frames);

Defensive patterns

Strategy: validation

Validate before calling

if (frames.Any(f => f.Size != frames[0].Size)) throw new ArgumentException("Frames must share one size.");

Type guard

bool uniformSize<T>(IReadOnlyList<ImageFrame<T>> frames) => frames.All(f => f.Size == frames[0].Size);

Try / catch

try { var image = new Image<Rgba32>(config, frames); } catch (ArgumentException ex) when (ex.Message.Contains("same size")) { /* normalize and retry */ }

Prevention

Normalize frame sizes immediately after decoding, before storing in a shared list
Group frames by Size and build one image per group
Use a shared Size constant for all frames produced by your pipeline

When it happens

Trigger: Constructing an Image<TPixel> from frames with differing Width/Height, e.g. mixing frames from differently sized images or decoders.

Common situations: Stitching frames decoded from multiple files or scaled variants into one animation image.

Related errors

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

Appendix: source

Thrown at src/ImageSharp/Image{TPixel}.cs:464

        for (int i = 0; i < this.frames.Count; i++)
        {
            this.frames[i].CopyMetadataFrom(sourceFrames[i]);
        }

        this.UpdateMetadata(source.Metadata);
    }

    private static Size ValidateFramesAndGetSize(IEnumerable<ImageFrame<TPixel>> frames)
    {
        Guard.NotNull(frames, nameof(frames));

        ImageFrame<TPixel>? rootFrame = frames.FirstOrDefault() ?? throw new ArgumentException("Must not be empty.", nameof(frames));

        Size rootSize = rootFrame.Size;

        if (frames.Any(f => f.Size != rootSize))
        {
            throw new ArgumentException("The provided frames must be of the same size.", nameof(frames));
        }

        return rootSize;
    }

    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    private void VerifyCoords(int x, int y)
    {
        if ((uint)x >= (uint)this.Width)
        {
            ThrowArgumentOutOfRangeException(nameof(x));
        }

        if ((uint)y >= (uint)this.Height)
        {
            ThrowArgumentOutOfRangeException(nameof(y));
        }
    }

View on GitHub (pinned to 59ce6af6fc)