SixLabors/ImageSharp · error · ImageFormatException

ANI bitmap resources cannot contain resolution variants.

Error message

ANI bitmap resources cannot contain resolution variants.

What it means

Raw BMP (DIB) resources in an ANI file hold exactly one image; only ICO/CUR directories can carry multiple resolution variants inside one physical resource. When the encoder detects a group of adjacent frames sharing a positive SequenceNumber (a resolution-variant group) whose format is Bmp, it refuses to encode.

Solutions

1. Set SequenceNumber to 0 (or distinct values) for BMP-format frames so each is an independent step.
2. Switch the frames' FrameFormat to Ico or Cur if resolution variants are genuinely needed.
3. Emit only one frame per animation step when using bitmap resources.

Example fix

// before
bmpFrame.Metadata.GetAniMetadata().SequenceNumber = 1; // groups variants
bmpFrame2.Metadata.GetAniMetadata().SequenceNumber = 1;
// after
bmpFrame.Metadata.GetAniMetadata().SequenceNumber = 0;
bmpFrame2.Metadata.GetAniMetadata().SequenceNumber = 0;

bool grouped = md.FrameFormat is AniFrameFormat.Bmp && md.SequenceNumber > 0 &&
    image.Frames.Skip(i + 1).Any(f => f.Metadata.GetAniMetadata().SequenceNumber == md.SequenceNumber);
if (grouped) throw new InvalidOperationException("BMP frames cannot be grouped as resolution variants.");

try { image.SaveAsAni(stream); }
catch (ImageFormatException ex) { Log(ex.Message); }

When it happens

Trigger: Encoding an ANI where multiple consecutive frames share the same positive AniFrameMetadata.SequenceNumber while their FrameFormat is AniFrameFormat.Bmp, producing a multi-variant group of bitmap resources.

Common situations: Building multi-resolution animated cursors from plain bitmap frames and reusing the SequenceNumber grouping used for ICO variants.

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

• ANI contains an unsupported embedded frame format.
• ANI cannot mix bitmap resources with ICO or CUR resources.
• ANI resolution variants must use the same embedded format.
• ANI resolution variants must use the same frame delay.
• ANI bitmap resources require a supported bit depth.

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

Appendix: source

Thrown at src/ImageSharp/Formats/Ani/AniEncoderCore.cs:104

            // Positive sequence numbers group adjacent resolution variants; non-positive values form independent steps.
            if (metadata.SequenceNumber > 0)
            {
                while (frameIndex + groupSize < image.Frames.Count && image.Frames[frameIndex + groupSize].Metadata.GetAniMetadata().SequenceNumber == metadata.SequenceNumber)
                {
                    groupSize++;
                }
            }

            if (bitmapResources != (metadata.FrameFormat is AniFrameFormat.Bmp))
            {
                // AF_ICON applies to the complete file, so raw DIB resources cannot coexist with ICO/CUR resources.
                throw new ImageFormatException("ANI cannot mix bitmap resources with ICO or CUR resources.");
            }

            if (bitmapResources && groupSize > 1)
            {
                // Only ICO/CUR directories can contain multiple resolution variants in one physical resource.
                throw new ImageFormatException("ANI bitmap resources cannot contain resolution variants.");
            }

            // All variants share one animation step, which requires one child format and one rate value.
            for (int i = 1; i < groupSize; i++)
            {
                AniFrameMetadata current = image.Frames[frameIndex + i].Metadata.GetAniMetadata();
                if (current.FrameFormat != metadata.FrameFormat)
                {
                    throw new ImageFormatException("ANI resolution variants must use the same embedded format.");
                }

                if (current.FrameDelay != metadata.FrameDelay)
                {
                    throw new ImageFormatException("ANI resolution variants must use the same frame delay.");
                }
            }

            uint frameDelay = metadata.FrameDelay is 0 ? displayRate : metadata.FrameDelay;

View on GitHub (pinned to 59ce6af6fc)