What causes "Cannot use the default value type instance to dither." in SixLabors/ImageSharp?

Initialize the dither with a real matrix, e.g. OrderedDither.Bayer4x4 or OrderedDither.Bayer8x8

SixLabors/ImageSharp · error · ImageProcessingException

Cannot use the default value type instance to dither.

Error message

Cannot use the default value type instance to dither.

What it means

ImageSharp's OrderedDither is a readonly struct whose default instance has a null thresholdMatrix, so applying it would corrupt output. ThrowDefaultInstance is a cold-path guard invoked from ApplyQuantizationDither and ApplyPaletteDither when a default(OrderedDither) is used. It signals the dither was never initialized with a real dithering matrix.

Solutions

Initialize the dither with a real matrix, e.g. OrderedDither.Bayer4x4 or OrderedDither.Bayer8x8
If storing a dither in a class, give the field an initializer or validate in the constructor
Check any serialization/deserialization path that reconstructs the dither struct and ensure the matrix is populated
Wrap the dithering call in a guard that compares the instance against default(OrderedDither) before applying

Example fix

// before
public OrderedDither Dither { get; set; }
image.Mutate(x => x.Quantize(new WebSafePaletteQuantizer(Dither)));
// after
public OrderedDither Dither { get; set; } = OrderedDither.Bayer8x8;

Defensive patterns

Strategy: validation

Validate before calling

static bool IsDefaultDither(OrderedDither d) => d.Equals(default); // or compare matrix emptiness
if (IsDefaultDither(dither)) throw new InvalidOperationException("Dither not initialized.");

Type guard

static bool HasDitherMatrix(OrderedDither d) => !d.Equals(default(OrderedDither));

Try / catch

try
{
    image.Mutate(x => x.Quantize(quantizer));
}
catch (ImageProcessingException ex) when (ex.Message.Contains("default value type instance"))
{
    // re-initialize dither with OrderedDither.Bayer8x8 and retry
}

Prevention

Always initialize OrderedDither fields/properties with a named ditherer (Bayer2x2/4x4/8x8, FloydSteinberg via ErrorDiffusionDither)
Use class-level initializers or constructor assignment rather than relying on struct defaults
Add a unit test that exercises the dithering path with your actual configuration
Never store ditherers in structs that get copied via default initialization

When it happens

Trigger: Calling ApplyDither/Quantizer dithering with default(OrderedDither), a struct field never assigned, or a Ditherers entry obtained via uninitialized code path.

Common situations: Declaring a dither field (e.g. 'public OrderedDither Dither;') without assigning it; using reflection or generic factories that produce the struct default; migrating code where the dither was previously a reference type and null-checks silently passed.

Related errors

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

Appendix: source

Thrown at src/ImageSharp/Processing/Processors/Dithering/OrderedDither.cs:227

        => obj is OrderedDither dither && this.Equals(dither);

    /// <inheritdoc/>
    [MethodImpl(InliningOptions.ShortMethod)]
    public bool Equals(OrderedDither other)
        => this.thresholdMatrix.Equals(other.thresholdMatrix) && this.modulusX == other.modulusX && this.modulusY == other.modulusY;

    /// <inheritdoc/>
    public bool Equals(IDither? other)
        => this.Equals((object?)other);

    /// <inheritdoc/>
    [MethodImpl(InliningOptions.ShortMethod)]
    public override int GetHashCode()
        => HashCode.Combine(this.thresholdMatrix, this.modulusX, this.modulusY);

    [MethodImpl(InliningOptions.ColdPath)]
    private static void ThrowDefaultInstance()
        => throw new ImageProcessingException("Cannot use the default value type instance to dither.");
}

View on GitHub (pinned to 59ce6af6fc)