SixLabors/ImageSharp · error · ImageFormatException

ANI cannot mix bitmap resources with ICO or CUR resources.

Error message

ANI cannot mix bitmap resources with ICO or CUR resources.

What it means

An ANI file applies its AF_ICON flag to the entire file: either all embedded resources are ICO/CUR directories or all are raw DIB bitmaps. The encoder counts bitmap resources in a frame group and compares against whether the group's declared FrameFormat is Bmp; a mismatch means the file would mix resource kinds, so it throws ImageFormatException.

Solutions

Make FrameFormat consistent across all frames destined for the same animation step (all Bmp or all Ico/Cur).
Split the image into two animations rather than mixing resource kinds in one file.
Recheck metadata assignment loops so a default FrameFormat doesn't leak into some frames.

Example fix

// before
frames[0].Metadata.GetAniMetadata().FrameFormat = AniFrameFormat.Bmp;
frames[1].Metadata.GetAniMetadata().FrameFormat = AniFrameFormat.Ico; // mixes kinds
// after
frames[0].Metadata.GetAniMetadata().FrameFormat = AniFrameFormat.Ico;
frames[1].Metadata.GetAniMetadata().FrameFormat = AniFrameFormat.Ico;

Defensive patterns

Strategy: validation

Validate before calling

var formats = image.Frames.Select(f => f.Metadata.GetAniMetadata().FrameFormat).Distinct().ToList();
if (formats.Count > 1) throw new InvalidOperationException("ANI frames must not mix Bmp with Ico/Cur formats.");

Try / catch

try { image.SaveAsAni(stream); }
catch (ImageFormatException ex) { /* normalize FrameFormat and retry */ }

Prevention

Keep FrameFormat uniform across the whole image when saving ANI.
Avoid appending frames from mixed-format sources without normalizing metadata.
Decide up front whether the animation uses ICO/CUR or BMP resources.

When it happens

Trigger: Encoding an ANI where frames within one animation step disagree — some frames marked FrameFormat = AniFrameFormat.Bmp while others are Ico/Cur (or vice versa), detected by bitmapResources != (metadata.FrameFormat is AniFrameFormat.Bmp).

Common situations: Appending frames from mixed sources (e.g. frames decoded from a CUR file plus frames generated as raw bitmaps) into one image before saving as ANI; per-frame metadata edited inconsistently.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

            if (metadata.FrameFormat is not (AniFrameFormat.Ico or AniFrameFormat.Cur or AniFrameFormat.Bmp))
            {
                // FrameFormat is public metadata and therefore must be validated before any container bytes are written.
                throw new ImageFormatException("ANI contains an unsupported embedded frame format.");
            }

            // 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)

View on GitHub (pinned to 59ce6af6fc)