HMCL-dev/HMCL · error · PngIntegrityException

Invalid truecolour bit-depth

Error message

Invalid truecolour bit-depth: %d

What it means

PngIntegrityException thrown when a truecolour (colour type 2) PNG declares a bit depth other than the legal 8 or 16. The ARGB8888 factory only implements Truecolour8 and Truecolour16, so any other depth indicates a corrupt IHDR. The TODO notes this belongs in header parsing.

Solutions

1. Validate that truecolour bit depth is 8 or 16 at header-parse time
2. Reject the file as corrupt before decoding
3. Re-obtain or re-encode the image with a compliant tool
4. Catch PngIntegrityException and surface an invalid-header error

Example fix

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

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

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

When it happens

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

Common situations: Corrupted or fuzzed PNG headers; hand-rolled encoders emitting wrong depth bytes; files altered by buggy converters; truncated/tampered downloads.

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 with alpha 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/9bee9a3104fcc21c. Report an issue: GitHub.

Appendix: source

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

                        return new IndexedColourBits(bytesPerScanline, bitmap, 7, 0x01, PngConstants.SHIFTS_1);
                    case 2:
                        return new IndexedColourBits(bytesPerScanline, bitmap, 3, 0x03, PngConstants.SHIFTS_2);
                    case 4:
                        return new IndexedColourBits(bytesPerScanline, bitmap, 1, 0x0F, PngConstants.SHIFTS_4);
                    case 8:
                        return new IndexedColour8(bytesPerScanline, bitmap);
                    default:
                        throw new PngIntegrityException(String.format("Invalid indexed colour bit-depth: %d", header.bitDepth)); // TODO: should be in header parse.
                }

            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());
        }
    }

View on GitHub (pinned to 24702dc5a0)