{"record":{"id":"5aee84cf27e84b68","repo":"HMCL-dev/HMCL","slug":"interlaced-images-are-not-yet-supported","errorCode":null,"errorMessage":"Interlaced images are not yet supported","messagePattern":"Interlaced images are not yet supported","errorType":"exception","errorClass":"PngFeatureException","httpStatus":null,"severity":"error","filePath":"HMCL/src/main/java/org/jackhuang/hmcl/ui/image/apng/chunks/PngHeader.java","lineNumber":209,"sourceCode":"            default:\n                throw new PngIntegrityException(\"Invalid bit depth \" + bitDepth);\n        }\n\n        // thanks to pypng\n        if (colourType.isIndexed() && bitDepth > 8) {\n            throw new PngIntegrityException(String.format(\n                    \"Indexed images (colour type %d) cannot have bitdepth > 8 (bit depth %d).\" +\n                            \" See http://www.w3.org/TR/2003/REC-PNG-20031110/#table111 .\", colourType.code, bitDepth));\n        }\n\n        if (bitDepth < 8 && !colourType.supportsSubByteDepth()) {\n            throw new PngIntegrityException(String.format(\n                    \"Illegal combination of bit depth (%d) and colour type (%d).\" +\n                            \" See http://www.w3.org/TR/2003/REC-PNG-20031110/#table111 .\", colourType.code, bitDepth));\n        }\n\n        if (interlaceMethod != 0) {\n            throw new PngFeatureException(\"Interlaced images are not yet supported\");\n        }\n    }\n\n    public static PngHeader from(DataInput dis) throws IOException, PngException {\n        int width = dis.readInt();\n        int height = dis.readInt();\n        byte bitDepth = dis.readByte();\n        PngColourType colourType = PngColourType.fromByte(dis.readByte());\n        byte compressionMethod = dis.readByte();\n        byte filterMethod = dis.readByte();\n        byte interlaceMethod = dis.readByte();\n        checkHeaderParameters(width, height, bitDepth, colourType, compressionMethod, filterMethod, interlaceMethod);\n        return new PngHeader(width, height, bitDepth, colourType, compressionMethod, filterMethod, interlaceMethod);\n    }\n}\n","sourceCodeStart":191,"sourceCodeEnd":225,"githubUrl":"https://github.com/HMCL-dev/HMCL/blob/24702dc5a0214034f4c27166d5fd30cad08cec19/HMCL/src/main/java/org/jackhuang/hmcl/ui/image/apng/chunks/PngHeader.java#L191-L225","documentation":"This is a capability guard in checkHeaderParameters: the APNG decoder does not implement Adam7 interlacing, so an IHDR declaring a non-zero interlace method cannot be decoded. It fires on valid-per-spec but unsupported images, signalling a deliberate decoder limitation rather than file corruption.","triggerScenarios":"Decoding a PNG saved with 'interlaced' (Adam7) option enabled, producing IHDR interlaceMethod = 1.","commonSituations":"Images exported from legacy tools or photo editors with interlacing enabled for progressive web display.","solutions":["Re-save the image as non-interlaced (e.g. ImageMagick: convert in.png -interlace none out.png).","If you control the encoder, write interlaceMethod = 0 in IHDR.","Use a decoder that supports Adam7 interlacing if interlaced input must be accepted.","Catch PngFeatureException to distinguish 'unsupported feature' from 'corrupt file' and report accordingly."],"exampleFix":"// before: assuming all PNGs decode\ndecode(pngBytes);\n// after: check interlace flag\nPngHeader h = PngHeader.from(...);\nif (h.getInterlaceMethod() != 0) {\n    pngBytes = convertToNonInterlaced(pngBytes); // or reject\n}\ndecode(pngBytes);","handlingStrategy":"fallback","validationCode":"if (interlaceMethod != 0) { /* convert or reject */ }","typeGuard":null,"tryCatchPattern":"try { decode(bytes); } catch (PngFeatureException e) { bytes = deinterlaceWithImageMagick(bytes); decode(bytes); }","preventionTips":["Save source assets as non-interlaced PNGs.","Detect interlaceMethod==1 at ingest and convert (convert in.png -interlace none out.png).","Document the no-interlace limitation for users.","Separate PngFeatureException handling from integrity errors."],"tags":["png","image-decoding","unsupported-feature","interlacing"],"backgroundTag":"unsupported-operation","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"}