SixLabors/ImageSharp · error · ArgumentException

Frame must have the same dimensions as the image.

Error message

Frame must have the same dimensions as the image.

What it means

ImageFrameCollection<TPixel> requires every frame added, inserted, or used to construct the collection to have exactly the same width and height as the root frame. Animation formats in ImageSharp are single-size, so mismatched frame dimensions are rejected with ArgumentException before the frame is stored.

Solutions

1. Resize or clone-resize the frame to the root image dimensions before adding it
2. Create the frame with new Size(image.Width, image.Height)
3. Adjust the root image size instead if the new frame's size is the intended one

Example fix

// before
image.Frames.AddFrame(otherFrame);
// after
using ImageFrame<TPixel> resized = otherFrame.Clone(image.Configuration, image.Size);
image.Frames.AddFrame(resized);

if (frame.Width != image.Width || frame.Height != image.Height) throw new ArgumentException("Frame size mismatch");

bool frameMatchesImage<T>(ImageFrame<T> f, Image<T> img) => f.Width == img.Width && f.Height == img.Height;

try { image.Frames.AddFrame(frame); } catch (ArgumentException ex) when (ex.ParamName == nameof(frame)) { /* resize and retry */ }

When it happens

Trigger: Calling AddFrame/InsertFrame (or the ImageFrameCollection constructor) with an ImageFrame<TPixel> whose Width/Height differ from RootFrame dimensions.

Common situations: Composing an animation from frames decoded at different sizes, or after resizing the root image without resizing all its frames.

Related errors

• The provided frames must be of the same size.
• Must not be empty.
• Source ICC profile is missing.
• Target ICC profile is missing.
• ICC conversion supports at most four input and output…

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

Appendix: source

Thrown at src/ImageSharp/ImageFrameCollection{TPixel}.cs:399

    public IEnumerator<ImageFrame<TPixel>> GetEnumerator()
    {
        this.EnsureNotDisposed();

        return this.frames.GetEnumerator();
    }

    /// <inheritdoc/>
    IEnumerator IEnumerable.GetEnumerator() => this.GetEnumerator();

    private void ValidateFrame(ImageFrame<TPixel> frame)
    {
        Guard.NotNull(frame, nameof(frame));

        if (this.Count != 0)
        {
            if (this.RootFrame.Width != frame.Width || this.RootFrame.Height != frame.Height)
            {
                throw new ArgumentException("Frame must have the same dimensions as the image.", nameof(frame));
            }
        }
    }

    /// <inheritdoc/>
    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            foreach (ImageFrame<TPixel> f in this.frames)
            {
                f.Dispose();
            }

            this.frames.Clear();
        }
    }

View on GitHub (pinned to 59ce6af6fc)