What causes "Must not be empty." in SixLabors/ImageSharp?

Check frames.Count()/Any() before constructing and throw or return early with a clearer message

SixLabors/ImageSharp · error · ArgumentException

Must not be empty.

Error message

Must not be empty.

What it means

The private Image<TPixel>.ValidateFramesAndGetSize uses the first frame of the supplied enumeration to derive the image size, so an empty enumeration has no valid size and yields an unusable image. ImageSharp throws ArgumentException("Must not be empty.") to prevent constructing an image without any frames.

Solutions

Check frames.Count()/Any() before constructing and throw or return early with a clearer message
Guard the source list so at least one frame always survives filtering
Catch ArgumentException around the constructor if frames come from an untrusted source

Example fix

// before
var image = new Image<Rgba32>(config, frames);
// after
if (!frames.Any()) throw new InvalidOperationException("No frames to build image from.");
var image = new Image<Rgba32>(config, frames);

Defensive patterns

Strategy: validation

Validate before calling

if (frames is null || !frames.Any()) throw new ArgumentException("At least one frame is required.");

Type guard

bool hasFrames<T>(IEnumerable<ImageFrame<T>> frames) => frames != null && frames.Any();

Try / catch

try { var image = new Image<Rgba32>(config, frames); } catch (ArgumentException ex) when (ex.Message.Contains("Must not be empty")) { /* handle empty input */ }

Prevention

Check frame count after any filtering/pipeline step before constructing
Treat decoders returning zero frames as a failure upstream
Never pass collections that may be empty; default to a single blank frame instead

When it happens

Trigger: Calling Image.LoadPixelData / new Image<TPixel>(configuration, metadata, frames) or Image.WrapMemory-based constructors with an empty frames collection.

Common situations: Filtering a decoded frame list before constructing an image (e.g. dropping all frames) and then passing the empty result; a decoder returning zero frames.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

    {
        Guard.NotNull(source, nameof(source));

        this.EnsureNotDisposed();

        ImageFrameCollection<TPixel> sourceFrames = source.Frames;
        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));
        }

View on GitHub (pinned to 59ce6af6fc)