Intervention/image · warning · AnalyzerException

Invalid pHYs chunk length

Error message

Invalid pHYs chunk length

What it means

After locating the pHYs chunk in a PNG, the parser reads the chunk's big-endian length field and requires exactly 9 bytes (4 for X pixels-per-unit, 4 for Y, 1 for unit). Any other length means the chunk is malformed and its 9-byte fixed layout cannot be trusted, so parsing aborts. The surrounding recovery chain catches this; through resolution() it degrades to the default fallback.

Source

Thrown at src/Drivers/Gd/Analyzers/ResolutionAnalyzer.php:206

            throw new AnalyzerException('Input must be PNG format');
        }

        $marker = '';

        while (!feof($handle)) {
            $marker = strlen($marker) < 4 ? $marker . fread($handle, 1) : substr($marker, 1) . fread($handle, 1);

            // find pHYs chunk
            if ($marker === 'pHYs') {
                // find length
                fseek($handle, -8, SEEK_CUR);
                $length = fread($handle, 4);
                $length = unpack('N', $length)[1];
                fseek($handle, 4, SEEK_CUR);

                // pHYs chunk must be exactly 9 bytes
                if ($length !== 9) {
                    throw new AnalyzerException('Invalid pHYs chunk length');
                }

                // read data
                $data = fread($handle, $length);

                $x = unpack('N', substr($data, 0, 4))[1];
                $y = unpack('N', substr($data, 4, 4))[1];
                $unit = ord(substr($data, 8, 1));

                // unit=1 means pixels per metre → convert to DPI
                // unit=0 means unknown unit (just a ratio) → return raw values
                if ($unit === 1) {
                    return [
                        round($x * .0254),
                        round($y * .0254),
                    ];
                }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Validate/re-encode the PNG: pngcheck file.png, then re-save with a conformant encoder
2. If the file must keep its (broken) chunk, call setResolution() manually and skip origin recovery
3. Reject structurally invalid uploads at ingest with pngcheck or a strict decoder before handing them to the library

Example fix

# verify and repair
pngcheck -v broken.png   # reports: pHYs: invalid chunk length
convert broken.png fixed.png  # re-encode with clean chunks

// run pngcheck or a strict decoder before processing
exec('pngcheck -q ' . escapeshellarg($path), $out, $code);
$pngStructurallyValid = $code === 0;

When it happens

Trigger: A PNG whose pHYs chunk has a length other than 9 (bit-corrupted file, chunk splicing bug in a compression tool, deliberately malformed test file).

Common situations: Files corrupted in transit or storage; PNGs rewritten by non-conformant optimizers; fuzzing corpora.

Related errors

• Input must be PNG format
• Failed to read image resolution
• Unable to read resolution from path
• Unable to read JFIF header
• Unable to read exif data

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/8a95e8839004a7ff. Report an issue: GitHub.