SixLabors/ImageSharp · error · ImageProcessingException

An error occurred when processing the image using

Error message

An error occurred when processing the image using {this.GetType().Name}. The processor changed the number of frames.

What it means

CloningImageProcessor verifies that cloning operations never add or remove frames: after cloning the source into the destination it compares frame counts. A mismatch throws ImageProcessingException, indicating the processor implementation itself corrupted the frame structure — a library-internal invariant rather than user input error.

Solutions

1. Do not add or remove frames inside a cloning processor; operate only on existing frame pixels
2. Perform frame-count changes on the Image<TPixel> before/after the processor runs, using a non-cloning flow
3. Update custom processors to the current ICloningImageProcessor contract after upgrading ImageSharp
4. Catch ImageProcessingException around custom processor execution to detect broken implementations

Example fix

// before
protected override void AfterImageApply(Image<TPixel> destination) => destination.Frames.RemoveFrame(0);
// after
protected override void AfterImageApply(Image<TPixel> destination) { /* leave frame count intact */ }

try { image.Mutate(ctx => ctx.ApplyProcessor(customCloningProcessor)); } catch (ImageProcessingException ex) when (ex.Message.Contains("number of frames")) { log.Error(ex, "Processor mutated frame count"); throw; }

When it happens

Trigger: A custom ICloningImageProcessor whose ApplyImageFrames/ApplyFrame logic or BeforeImageApply/AfterImageApply mutates the destination's frame collection; calling Execute/CloneAndExecute on an image whose frames changed concurrently during processing.

Common situations: Writing a custom clone processor that calls Frames.Add/Remove or CreateFrame inside the processing pipeline; buggy custom processor implementations after an ImageSharp version upgrade changed the cloning contract.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• The ANI file contains an unsupported frame format.
• Must not be empty.
• Cannot remove last frame.
• Frame must have the same dimensions as the image.
• The provided frames must be of the same size.

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

Appendix: source

Thrown at src/ImageSharp/Processing/Processors/CloningImageProcessor{TPixel}.cs:177

        ImageFrame<TPixel>[] destinationFrames = new ImageFrame<TPixel>[source.Frames.Count];
        for (int i = 0; i < destinationFrames.Length; i++)
        {
            destinationFrames[i] = new ImageFrame<TPixel>(
                this.Configuration,
                destinationSize.Width,
                destinationSize.Height,
                source.Frames[i].Metadata.DeepClone());
        }

        // Use the overload to prevent an extra frame being added.
        return new Image<TPixel>(this.Configuration, source.Metadata.DeepClone(), destinationFrames);
    }

    private void CheckFrameCount(Image<TPixel> a, Image<TPixel> b)
    {
        if (a.Frames.Count != b.Frames.Count)
        {
            throw new ImageProcessingException($"An error occurred when processing the image using {this.GetType().Name}. The processor changed the number of frames.");
        }
    }
}

View on GitHub (pinned to 59ce6af6fc)