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

ErrorDither is a readonly struct; its default instance has a null/empty matrix, so applying it would read out-of-bounds. ApplyQuantizationDither and ApplyPaletteDither call ThrowDefaultInstance, throwing ImageProcessingException 'Cannot use the default value type instance to dither.'

Solutions

1. Use the predefined static instances: ErrorDither.FloydSteinberg, ErrorDither.Burkes, ErrorDither.Atkinson, ErrorDither.Sierra3, ErrorDither.Sierra2, ErrorDither.SierraLite, ErrorDither.Stucki, ErrorDither.JarvisJudiceNinke
2. If dithering should be optional, pass null (or use IDither and omit it) instead of default(ErrorDither)
3. Check for default before applying: if (dither == default) throw or skip
4. Fix config/binding code so the named dither resolves to a known static instance

Example fix

// before
IDither dither = default;
options.Dither = dither;
// after
options.Dither = ErrorDither.FloydSteinberg; // or null to disable

if (dither is ErrorDither ed && ed == default) throw new InvalidOperationException("Dither not initialized");

static bool IsInitialized(ErrorDither d) => d != default;

try { options.Dither = dither; } catch (ImageProcessingException ex) when (ex.Message.Contains("default value type instance")) { options.Dither = ErrorDither.FloydSteinberg; }

When it happens

Trigger: Declaring an uninitialized field/property of type ErrorDither (default(ErrorDither)) and passing it to e.g. Quantizer options Dither property, or an API accepting IDither where a default ErrorDither was assigned; a struct array element never initialized.

Common situations: Using 'default' as a placeholder for optional dithering; new ErrorDither[...] arrays with untouched elements; DI/config binding creating a default instance when the dither name didn't resolve.

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

• Cannot use the default value type instance to dither.
• Frame Quantizer palette has not been built.

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

Appendix: source

Thrown at src/ImageSharp/Processing/Processors/Dithering/ErrorDither.cs:240

    /// <inheritdoc/>
    public override bool Equals(object? obj)
        => obj is ErrorDither dither && this.Equals(dither);

    /// <inheritdoc/>
    public bool Equals(ErrorDither other)
        => this.offset == other.offset && this.matrix.Equals(other.matrix);

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

    /// <inheritdoc/>
    public override int GetHashCode()
        => HashCode.Combine(this.offset, this.matrix);

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