{"record":{"id":"8c606d437c62f22e","repo":"SixLabors/ImageSharp","slug":"cicp-matrix-coefficients-other-than-identity-are-not","errorCode":null,"errorMessage":"CICP matrix coefficients other than Identity are not supported in PNG","messagePattern":"CICP matrix coefficients other than Identity are not supported in PNG","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"src/ImageSharp/Formats/Png/PngEncoderCore.cs","lineNumber":1068,"sourceCode":"    }\n\n    /// <summary>\n    /// Writes the CICP profile chunk\n    /// </summary>\n    /// <param name=\"stream\">The <see cref=\"Stream\"/> containing image data.</param>\n    /// <param name=\"metaData\">The image meta data.</param>\n    /// <exception cref=\"NotSupportedException\">CICP matrix coefficients other than Identity are not supported in PNG.</exception>\n    private void WriteCicpChunk(Stream stream, ImageMetadata metaData)\n    {\n        if (metaData.CicpProfile is null)\n        {\n            return;\n        }\n\n        // by spec, the matrix coefficients must be set to Identity\n        if (metaData.CicpProfile.MatrixCoefficients != Metadata.Profiles.Cicp.CicpMatrixCoefficients.Identity)\n        {\n            throw new NotSupportedException(\"CICP matrix coefficients other than Identity are not supported in PNG\");\n        }\n\n        Span<byte> outputBytes = this.chunkDataBuffer[..4];\n        outputBytes[0] = (byte)metaData.CicpProfile.ColorPrimaries;\n        outputBytes[1] = (byte)metaData.CicpProfile.TransferCharacteristics;\n        outputBytes[2] = (byte)metaData.CicpProfile.MatrixCoefficients;\n        outputBytes[3] = (byte)(metaData.CicpProfile.FullRange ? 1 : 0);\n        this.WriteChunk(stream, PngChunkType.Cicp, outputBytes);\n    }\n\n    /// <summary>\n    /// Writes the color profile chunk.\n    /// </summary>\n    /// <param name=\"stream\">The stream to write to.</param>\n    /// <param name=\"metaData\">The image meta data.</param>\n    private void WriteColorProfileChunk(Stream stream, ImageMetadata metaData)\n    {\n        if (metaData.IccProfile is null)","sourceCodeStart":1050,"sourceCodeEnd":1086,"githubUrl":"https://github.com/SixLabors/ImageSharp/blob/59ce6af6fc29027cda277ef62d4d1694a8acce91/src/ImageSharp/Formats/Png/PngEncoderCore.cs#L1050-L1086","documentation":"PngEncoderCore throws this NotSupportedException when writing a cICP chunk for metadata whose CICP MatrixCoefficients is not Identity. The PNG cICP specification requires matrix coefficients to be Identity; other values (e.g. BT.709 or BT.601 matrices from video-oriented profiles) cannot be represented in PNG.","triggerScenarios":"Calling Image.Save/Mutate-save to PNG on an image whose metadata contains a CicpProfile copied from a video source (HEVC/AV1 streams) with a non-Identity MatrixCoefficients value.","commonSituations":"Transcoding video frames (HDR SDR-transfer content with BT.2020/709 matrix tags) into PNG, or blindly copying CICP metadata from JPEG-XL/AVIF to PNG.","solutions":["Clear or replace the image's CicpProfile metadata before saving (set a profile with MatrixCoefficients.Identity, or remove it entirely).","Strip video-derived metadata when transcoding to PNG and let the encoder choose defaults.","Save to a format that supports non-Identity matrices (e.g. AVIF) if the matrix coefficient must be preserved.","Remove the cicp metadata chunk with an image metadata editor if re-encoding from source is not possible."],"exampleFix":"// before: keeping video-derived CICP\nusing var image = Image.Load(\"frame.avif\");\nimage.SaveAsPng(\"frame.png\"); // throws\n// after\nusing var image = Image.Load(\"frame.avif\");\nimage.Metadata.RemoveCicpProfile(); // or set MatrixCoefficients = Identity\nimage.SaveAsPng(\"frame.png\");","handlingStrategy":"validation","validationCode":"// ensure CICP metadata is PNG-compatible before saving\nvar cicp = image.Metadata.GetCicpProfile();\nif (cicp is not null && cicp.MatrixCoefficients != Metadata.Profiles.Cicp.CicpMatrixCoefficients.Identity)\n{\n    image.Metadata.RemoveCicpProfile(); // or construct one with Identity\n}","typeGuard":"static bool IsPngCompatibleCicp(CicpProfile? p) =>\n    p is null || p.MatrixCoefficients == CicpMatrixCoefficients.Identity;","tryCatchPattern":"try\n{\n    image.SaveAsPng(path);\n}\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"CICP matrix coefficients\"))\n{\n    image.Metadata.RemoveCicpProfile();\n    image.SaveAsPng(path); // retry without the incompatible profile\n}","preventionTips":["Strip or normalize CICP metadata when transcoding from video formats (AVIF/HEVC) to PNG.","Remember PNG only allows Identity matrix coefficients per spec.","Route content that must keep non-Identity matrices to AVIF/JXL instead."],"tags":["png","cicp","metadata","encoding"],"backgroundTag":"unsupported-enum-value","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"}