HMCL-dev/HMCL · error · PngIntegrityException

Invalid truecolour with alpha bit-depth

Error message

Invalid truecolour with alpha bit-depth: %d

What it means

PngIntegrityException thrown when a truecolour-with-alpha (colour type 6) PNG declares a bit depth other than the legal 8 or 16. The factory only provides Truecolour8Alpha and Truecolour16Alpha, so other depths mean the IHDR is malformed. Like the other bit-depth checks, the TODO indicates it should live in header parsing.

Solutions

1. Validate the colour-type/bit-depth pair (type 6 requires 8 or 16) before constructing the processor
2. Reject the file as structurally invalid at parse time
3. Re-encode or re-download the image from a trusted source
4. Catch PngIntegrityException and report a corrupt PNG header

Example fix

// before
Argb8888ScanlineProcessor p = Argb8888Processors.from(header, bitmap); // throws for bitDepth=2
// after
if (header.colourType == PngColourType.PNG_TRUECOLOUR_WITH_ALPHA
        && header.bitDepth != 8 && header.bitDepth != 16) {
    throw new PngIntegrityException("IHDR bit depth invalid for truecolour+alpha: " + header.bitDepth);
}
Argb8888ScanlineProcessor p = Argb8888Processors.from(header, bitmap);

if (header.colourType == PngColourType.PNG_TRUECOLOUR_WITH_ALPHA
        && !(header.bitDepth == 8 || header.bitDepth == 16)) {
    throw new IllegalArgumentException("Invalid truecolour+alpha bit depth: " + header.bitDepth);
}

try {
    processor = Argb8888Processors.from(header, bitmap);
} catch (PngIntegrityException e) {
    throw new IOException("Corrupt PNG IHDR (RGBA depth): " + e.getMessage(), e);
}

When it happens

Trigger: Calling Argb8888Processors.from with a header of colourType PNG_TRUECOLOUR_WITH_ALPHA and bitDepth not in {8,16} — e.g. 1, 2, 4, or corrupted bytes.

Common situations: Fuzzed RGBA PNGs; damaged headers from partial downloads; buggy encoders copying depth bytes across colour-type conversions; hand-crafted test binaries.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid greyscale bit-depth
• Invalid greyscale-with-alpha bit-depth
• Invalid indexed colour bit-depth
• Invalid truecolour bit-depth
• Valid greyscale bit depths are 1, 2, 4, 8, not

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/a7425a3b87184cda. Report an issue: GitHub.

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/ui/image/apng/argb8888/Argb8888Processors.java:93

            case PNG_TRUECOLOUR:
                switch (header.bitDepth) {
                    case 8:
                        return new Truecolour8(bytesPerScanline, bitmap);
                    case 16:
                        return new Truecolour16(bytesPerScanline, bitmap);
                    default:
                        throw new PngIntegrityException(String.format("Invalid truecolour bit-depth: %d", header.bitDepth)); // TODO: should be in header parse.

                }

            case PNG_TRUECOLOUR_WITH_ALPHA:
                switch (header.bitDepth) {
                    case 8:
                        return new Truecolour8Alpha(bytesPerScanline, bitmap);
                    case 16:
                        return new Truecolour16Alpha(bytesPerScanline, bitmap);
                    default:
                        throw new PngIntegrityException(String.format("Invalid truecolour with alpha bit-depth: %d", header.bitDepth)); // TODO: should be in header parse.

                }

            default:
                throw new PngFeatureException("ARGB8888 doesn't support PNG mode " + header.colourType.name());
        }
    }

    /**
     * Transforms 1-, 2-, 4-bit indexed colour source pixels to ARGB8888 pixels.
     */
    public static class IndexedColourBits extends Argb8888ScanlineProcessor {

        private int highBit;
        private int mask;
        private byte[] shifts;

        public IndexedColourBits(int bytesPerScanline, Argb8888Bitmap bitmap, int highBit, int mask, byte[] shifts) {

View on GitHub (pinned to 24702dc5a0)