{"record":{"id":"8a9bea0de7daeb33","repo":"SixLabors/ImageSharp","slug":"cannot-use-the-default-value-type-instance-to-dither-8a9bea","errorCode":null,"errorMessage":"Cannot use the default value type instance to dither.","messagePattern":"Cannot use the default value type instance to dither\\.","errorType":"exception","errorClass":"ImageProcessingException","httpStatus":null,"severity":"error","filePath":"src/ImageSharp/Processing/Processors/Dithering/OrderedDither.cs","lineNumber":227,"sourceCode":"        => obj is OrderedDither dither && this.Equals(dither);\n\n    /// <inheritdoc/>\n    [MethodImpl(InliningOptions.ShortMethod)]\n    public bool Equals(OrderedDither other)\n        => this.thresholdMatrix.Equals(other.thresholdMatrix) && this.modulusX == other.modulusX && this.modulusY == other.modulusY;\n\n    /// <inheritdoc/>\n    public bool Equals(IDither? other)\n        => this.Equals((object?)other);\n\n    /// <inheritdoc/>\n    [MethodImpl(InliningOptions.ShortMethod)]\n    public override int GetHashCode()\n        => HashCode.Combine(this.thresholdMatrix, this.modulusX, this.modulusY);\n\n    [MethodImpl(InliningOptions.ColdPath)]\n    private static void ThrowDefaultInstance()\n        => throw new ImageProcessingException(\"Cannot use the default value type instance to dither.\");\n}\n","sourceCodeStart":209,"sourceCodeEnd":229,"githubUrl":"https://github.com/SixLabors/ImageSharp/blob/59ce6af6fc29027cda277ef62d4d1694a8acce91/src/ImageSharp/Processing/Processors/Dithering/OrderedDither.cs#L209-L229","documentation":"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.","triggerScenarios":"Calling ApplyDither/Quantizer dithering with default(OrderedDither), a struct field never assigned, or a Ditherers entry obtained via uninitialized code path.","commonSituations":"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.","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"],"exampleFix":"// before\npublic OrderedDither Dither { get; set; }\nimage.Mutate(x => x.Quantize(new WebSafePaletteQuantizer(Dither)));\n// after\npublic OrderedDither Dither { get; set; } = OrderedDither.Bayer8x8;","handlingStrategy":"validation","validationCode":"static bool IsDefaultDither(OrderedDither d) => d.Equals(default); // or compare matrix emptiness\nif (IsDefaultDither(dither)) throw new InvalidOperationException(\"Dither not initialized.\");","typeGuard":"static bool HasDitherMatrix(OrderedDither d) => !d.Equals(default(OrderedDither));","tryCatchPattern":"try\n{\n    image.Mutate(x => x.Quantize(quantizer));\n}\ncatch (ImageProcessingException ex) when (ex.Message.Contains(\"default value type instance\"))\n{\n    // re-initialize dither with OrderedDither.Bayer8x8 and retry\n}","preventionTips":["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"],"tags":["dithering","image-processing","uninitialized-value"],"backgroundTag":"uninitialized-value-type","analyzedSha":"59ce6af6fc29027cda277ef62d4d1694a8acce91","analyzedAt":"2026-09-13T18:34:59.331Z","contentChangedAt":"2026-09-13T18:34:59.331Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}