SixLabors/ImageSharp · error · ImageFormatException

ANI contains an unsupported embedded frame format.

Error message

ANI contains an unsupported embedded frame format.

What it means

The ANI encoder groups frames by their per-frame metadata and requires each embedded frame resource to be one of the supported child formats: ICO, CUR, or raw BMP (DIB). Before writing any container bytes, it validates AniFrameMetadata.FrameFormat and throws ImageFormatException if the value falls outside those three. This prevents emitting an ANI file that other readers cannot parse.

Solutions

1. Inspect every frame's image.Frames[i].Metadata.GetAniMetadata().FrameFormat before encoding and set it to Ico, Cur, or Bmp.
2. If frames came from a decoded ANI, drop or replace frames whose format is unsupported instead of re-encoding them.
3. Validate all enum values with Enum.IsDefined against AniFrameFormat before assigning them to metadata.

Example fix

// before
frame.Metadata.GetAniMetadata().FrameFormat = (AniFrameFormat)7; // invalid
// after
frame.Metadata.GetAniMetadata().FrameFormat = AniFrameFormat.Ico;

var fmt = frame.Metadata.GetAniMetadata().FrameFormat;
if (fmt is not (AniFrameFormat.Ico or AniFrameFormat.Cur or AniFrameFormat.Bmp))
    throw new InvalidOperationException($"Unsupported ANI frame format: {fmt}");

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

When it happens

Trigger: Calling Image.EncodeAsAni / SaveAsAni while a frame's AniFrameMetadata.FrameFormat was set (programmatically or by a previous decode) to a value other than AniFrameFormat.Ico, Cur, or Bmp — e.g. a custom/invalid enum cast or metadata copied from an unsupported source.

Common situations: Copying frame metadata between images of different formats, manually constructing AniFrameMetadata with an uninitialized or out-of-range enum value, or decoding an ANI whose frame format mapped to a value this encoder does not re-encode.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• ANI cannot mix bitmap resources with ICO or CUR resources.
• ANI bitmap resources cannot contain resolution variants.
• 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/dce2e7f61f9a7dcc. Report an issue: GitHub.

Appendix: source

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

            throw new ImageFormatException("ANI bitmap resources require a supported bit depth.");
        }

        if (bitmapResources && imageMetadata.Planes is not (0 or 1))
        {
            throw new ImageFormatException("ANI bitmap resources require exactly one color plane.");
        }

        // This validation pass derives the fixed ANI header and largest icon directory without allocating a grouping graph.
        // Encoding repeats the linear grouping scan below, trading a cheap pass for zero per-group collections.
        for (int frameIndex = 0; frameIndex < image.Frames.Count;)
        {
            AniFrameMetadata metadata = image.Frames[frameIndex].Metadata.GetAniMetadata();
            int groupSize = 1;

            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)

View on GitHub (pinned to 59ce6af6fc)