{"record":{"id":"d175b10a5fc208b2","repo":"OpenRA/OpenRA","slug":"unknown-pixel-format","errorCode":null,"errorMessage":"Unknown pixel format","messagePattern":"Unknown pixel format","errorType":"exception","errorClass":"InvalidDataException","httpStatus":null,"severity":"error","filePath":"OpenRA.Game/FileFormats/Png.cs","lineNumber":481,"sourceCode":"\t\t\treturn isPng;\n\t\t}\n\n\t\t[Flags]\n\t\tenum PngColorType : byte { Indexed = 1, Color = 2, Alpha = 4 }\n\t\tenum PngFilter : byte { None, Sub, Up, Average, Paeth }\n\n\t\tstatic bool IsPaletted(byte bitDepth, PngColorType colorType)\n\t\t{\n\t\t\tif (bitDepth <= 8 && colorType == (PngColorType.Indexed | PngColorType.Color))\n\t\t\t\treturn true;\n\n\t\t\tif (bitDepth == 8 && colorType == (PngColorType.Color | PngColorType.Alpha))\n\t\t\t\treturn false;\n\n\t\t\tif (bitDepth == 8 && colorType == PngColorType.Color)\n\t\t\t\treturn false;\n\n\t\t\tthrow new InvalidDataException(\"Unknown pixel format\");\n\t\t}\n\n\t\tstatic void WritePngChunk(MemoryStream output, uint type, MemoryStream input)\n\t\t{\n\t\t\tSpan<byte> header = stackalloc byte[8];\n\t\t\tBinaryPrimitives.WriteInt32BigEndian(header[..4], (int)input.Length);\n\t\t\tBinaryPrimitives.WriteUInt32BigEndian(header[4..], type);\n\n\t\t\tif (!input.TryGetBuffer(out var dataSegment))\n\t\t\t\tdataSegment = new ArraySegment<byte>(input.ToArray());\n\n\t\t\tReadOnlySpan<byte> data = dataSegment.AsSpan(0, (int)input.Length);\n\n\t\t\toutput.Write(header);\n\t\t\toutput.Write(data);\n\n\t\t\tvar crc = 0xFFFFFFFF;\n\t\t\tcrc = CRC32.Update(crc, header[4..]);","sourceCodeStart":463,"sourceCodeEnd":499,"githubUrl":"https://github.com/OpenRA/OpenRA/blob/a520984d91eda9de48a62b1d15c1e3bad0d4fb1a/OpenRA.Game/FileFormats/Png.cs#L463-L499","documentation":"Thrown by the static IsPaletted() helper when the combination of bit depth and PNG color type does not match any of the three recognized patterns: (1) bitDepth <= 8 with colorType Indexed|Color (palette-based), (2) bitDepth == 8 with colorType Color|Alpha (RGBA), or (3) bitDepth == 8 with colorType Color (RGB). Any other combination is treated as an unknown pixel format.","triggerScenarios":"Constructing `new Png(stream)` where the IHDR chunk specifies a bit depth / color type combination not in the supported set. For example: 16-bit depth, grayscale (colorType=0), grayscale+alpha (colorType=4), or bitDepth < 8 with a non-indexed color type. IsPaletted() is called during IHDR parsing and throws for unsupported formats.","commonSituations":"A 16-bit-per-channel PNG was provided (OpenRA only supports 8-bit). A grayscale PNG (color type 0) was used instead of RGB/RGBA. A grayscale+alpha PNG (color type 4). An unusual bit depth like 2 or 4 with a non-indexed color type.","solutions":["Re-export the PNG as 8-bit RGB (color type 2) or 8-bit RGBA (color type 6).","Convert to 8-bit: `convert input.png -depth 8 output.png`.","Convert grayscale to RGB: `convert input.png -type TrueColor output.png`.","For palette-based images, ensure bit depth is <= 8 with color type 3 (indexed)."],"exampleFix":"# convert 16-bit or grayscale PNG to 8-bit RGB\nconvert input.png -depth 8 -type TrueColor output.png\n\n# or for RGBA\nconvert input.png -depth 8 -type TrueColorAlpha output.png","handlingStrategy":"validation","validationCode":"// Check IHDR bit depth and color type before loading\nif (!Png.Verify(stream)) return;\nstream.Position = 8 + 4 + 4; // skip sig + length + type\nvar ihdr = new byte[13];\nstream.Read(ihdr, 0, 13);\nstream.Seek(0, SeekOrigin.Begin);\nvar bitDepth = ihdr[8];\nvar colorType = ihdr[9]; // 0=gray, 2=rgb, 3=indexed, 4=gray+alpha, 6=rgba\n\nif (bitDepth != 8 && !(bitDepth <= 8 && colorType == 3))\n    throw new InvalidDataException($\"Unsupported bit depth {bitDepth}. Use 8-bit.\");\nif (colorType != 2 && colorType != 3 && colorType != 6)\n    throw new InvalidDataException($\"Unsupported color type {colorType}. Use RGB(2), RGBA(6), or Indexed(3).\");","typeGuard":null,"tryCatchPattern":"try\n{\n    var png = new Png(stream);\n}\ncatch (InvalidDataException ex) when (ex.Message == \"Unknown pixel format\")\n{\n    logger.LogError($\"Unsupported PNG pixel format — re-export as 8-bit RGB or RGBA: {ex.Message}\");\n}","preventionTips":["Export all game assets as 8-bit RGB (color type 2) or 8-bit RGBA (color type 6).","Avoid grayscale PNGs (color type 0/4) — convert to RGB before use.","Avoid 16-bit depth PNGs — always use 8-bit.","Add an asset validation step: `identify -format '%[depth] %[colorspace]' *.png` to check all assets."],"tags":["png","file-format","pixel-format","bit-depth"],"backgroundTag":null,"analyzedSha":"a520984d91eda9de48a62b1d15c1e3bad0d4fb1a","analyzedAt":"2026-08-13T15:30:14.787Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}