{"record":{"id":"972b5bdb7f7fd15c","repo":"HMCL-dev/HMCL","slug":"argb8888-doesn-t-support-png-mode","errorCode":null,"errorMessage":"ARGB8888 doesn't support PNG mode ","messagePattern":"ARGB8888 doesn't support PNG mode ","errorType":"exception","errorClass":"PngFeatureException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/ui/image/apng/argb8888/Argb8888Processors.java","lineNumber":98,"sourceCode":"                        return new Truecolour16(bytesPerScanline, bitmap);\n                    default:\n                        throw new PngIntegrityException(String.format(\"Invalid truecolour bit-depth: %d\", header.bitDepth)); // TODO: should be in header parse.\n\n                }\n\n            case PNG_TRUECOLOUR_WITH_ALPHA:\n                switch (header.bitDepth) {\n                    case 8:\n                        return new Truecolour8Alpha(bytesPerScanline, bitmap);\n                    case 16:\n                        return new Truecolour16Alpha(bytesPerScanline, bitmap);\n                    default:\n                        throw new PngIntegrityException(String.format(\"Invalid truecolour with alpha bit-depth: %d\", header.bitDepth)); // TODO: should be in header parse.\n\n                }\n\n            default:\n                throw new PngFeatureException(\"ARGB8888 doesn't support PNG mode \" + header.colourType.name());\n        }\n    }\n\n    /**\n     * Transforms 1-, 2-, 4-bit indexed colour source pixels to ARGB8888 pixels.\n     */\n    public static class IndexedColourBits extends Argb8888ScanlineProcessor {\n\n        private int highBit;\n        private int mask;\n        private byte[] shifts;\n\n        public IndexedColourBits(int bytesPerScanline, Argb8888Bitmap bitmap, int highBit, int mask, byte[] shifts) {\n            this(bytesPerScanline, bitmap, highBit, mask, shifts, null);\n        }\n\n        public IndexedColourBits(int bytesPerScanline, Argb8888Bitmap bitmap, int highBit, int mask, byte[] shifts, Argb8888Palette palette) {\n            super(bytesPerScanline, bitmap);","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/ui/image/apng/argb8888/Argb8888Processors.java#L80-L116","documentation":"PngFeatureException thrown when the PNG colour type is not one of the five standard types the ARGB8888 backend handles (0, 2, 3, 4, 6). Any other/unrecognized colourType value falls through the switch's default branch and is rejected as an unsupported feature rather than a corrupt file.","triggerScenarios":"Calling Argb8888Processors.from with a header whose colourType is not one of PNG_GREYSCALE, PNG_TRUECOLOUR, PNG_INDEXED_COLOUR, PNG_GREYSCALE_WITH_ALPHA, PNG_TRUECOLOUR_WITH_ALPHA — e.g. a newly added or nonstandard colour-type byte.","commonSituations":"PNG files with reserved or future colour-type values; memory-corrupted IHDR colour byte that still looks like a type enum; custom extended PNG variants; enum deserialization producing an unexpected constant.","solutions":["Use a decoder backend that supports the image's colour type, or convert the image to a standard type (e.g. RGBA 8-bit) before decoding","Validate the IHDR colour type against {0,2,3,4,6} during header parsing and reject nonstandard values early","Re-encode the image with a mainstream tool to normalize the colour type","Catch PngFeatureException and route to an alternative decoder or show a 'format not supported' message"],"exampleFix":"// before: unsupported colour type byte 7 decoded directly\nArgb8888ScanlineProcessor p = Argb8888Processors.from(header, bitmap); // throws\n// after: pre-validate and convert if needed\nint typeByte = header.colourType.ordinal(); // or raw value\nif (typeByte != 0 && typeByte != 2 && typeByte != 3 && typeByte != 4 && typeByte != 6) {\n    header = convertToRgba8(header, bitmap); // or reject the file\n}\nArgb8888ScanlineProcessor p = Argb8888Processors.from(header, bitmap);","handlingStrategy":"try-catch","validationCode":"int t = header.colourTypeValue();\nif (t != 0 && t != 2 && t != 3 && t != 4 && t != 6) {\n    throw new IllegalArgumentException(\"Nonstandard PNG colour type: \" + t);\n}","typeGuard":"boolean isStandardColourType(PngHeader header) {\n    switch (header.colourType) {\n        case PNG_GREYSCALE:\n        case PNG_TRUECOLOUR:\n        case PNG_INDEXED_COLOUR:\n        case PNG_GREYSCALE_WITH_ALPHA:\n        case PNG_TRUECOLOUR_WITH_ALPHA:\n            return true;\n        default:\n            return false;\n    }\n}","tryCatchPattern":"try {\n    processor = Argb8888Processors.from(header, bitmap);\n} catch (PngFeatureException e) {\n    // unknown colour type: try generic decoder or notify 'format not supported'\n    processor = genericDecoderFactory.from(header, bitmap);\n}","preventionTips":["Reject nonstandard colour-type bytes at header parse time","Keep an alternative decoder path for exotic PNG variants","Constrain the enum parse so unknown bytes cannot become colourType values","Re-encode unusual images with mainstream tools before ingestion"],"tags":["png","colour-type","unsupported-feature","format"],"backgroundTag":"unsupported-enum-value","analyzedSha":"24702dc5a0214034f4c27166d5fd30cad08cec19","analyzedAt":"2026-09-10T12:36:46.680Z","contentChangedAt":"2026-09-10T12:36:46.680Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}