HMCL-dev/HMCL · error · PngIntegrityException

Valid PNG colour types are 0, 2, 3, 4, 6. Type

Error message

Valid PNG colour types are 0, 2, 3, 4, 6. Type '%d' is invalid

What it means

Thrown by PngColourType.fromByte as PngIntegrityException when the IHDR colour type byte is not one of the valid PNG colour types 0 (greyscale), 2 (truecolour), 3 (indexed), 4 (greyscale+alpha), 6 (truecolour+alpha). Values 1, 5, 7+ are invalid per the PNG spec.

Solutions

1. Re-download or re-export the PNG file — the header is corrupt
2. Verify the file starts with a valid PNG signature and IHDR using pngcheck
3. Catch PngIntegrityException during parse and reject the file with a clear message
4. If processing untrusted input, validate signature + IHDR fields before full decode

Example fix

// before
PngColourType ct = PngColourType.fromByte(ihdrColourType); // throws on 1/5/7
// after
if (ihdrColourType == 0 || ihdrColourType == 2 || ihdrColourType == 3
        || ihdrColourType == 4 || ihdrColourType == 6) {
    ct = PngColourType.fromByte(ihdrColourType);
} else {
    rejectFile("Unsupported colour type " + ihdrColourType);
}

int ct = readIhdrColourType(bytes);
if (ct != 0 && ct != 2 && ct != 3 && ct != 4 && ct != 6) {
    throw new IllegalArgumentException("Invalid PNG colour type: " + ct);
}

static boolean isKnownColourType(byte b) {
    int v = b & 0xFF;
    return v == 0 || v == 2 || v == 3 || v == 4 || v == 6;
}

try {
    colourType = PngColourType.fromByte(b);
} catch (PngIntegrityException e) {
    throw new IOException("Corrupt PNG header: " + e.getMessage(), e);
}

When it happens

Trigger: Parsing a PNG whose IHDR chunk contains colour type 1, 5, or >= 7 — i.e. a corrupt header, a truncated/mangled file, or non-PNG data misidentified as a PNG.

Common situations: Corrupted downloads or disk sectors; files with overwritten headers; crafted PNGs in security testing; text files renamed to .png.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Valid greyscale bit depths are 1, 2, 4, 8, not
• Received tRNS data length is invalid. Should be >1 && <
• Invalid bit depth
• Indexed images (colour type ) cannot have bitdepth > 8 (bit…
• Illegal combination of bit depth

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

Appendix: source

Thrown at HMCL/src/main/java/org/jackhuang/hmcl/ui/image/apng/PngColourType.java:58

    public boolean supportsSubByteDepth() {
        return code == 0 || code == 3;
    }

    public static PngColourType fromByte(byte b) throws PngException {
        switch (b) {
            case 0:
                return PNG_GREYSCALE;
            case 2:
                return PNG_TRUECOLOUR;
            case 3:
                return PNG_INDEXED_COLOUR;
            case 4:
                return PNG_GREYSCALE_WITH_ALPHA;
            case 6:
                return PNG_TRUECOLOUR_WITH_ALPHA;
            default:
                throw new PngIntegrityException(String.format("Valid PNG colour types are 0, 2, 3, 4, 6. Type '%d' is invalid", b));
        }
    }
}

View on GitHub (pinned to 24702dc5a0)