How to Catch Truncated JPEGs Before Thumbnail Generation

A JPEG can have a readable header and still be missing compressed pixel data. If your thumbnail worker only calls Image.open() or verify(), it may discover the problem later during resize or save. Force a full decode before accepting the image for thumbnail processing.

This tutorial builds a JPEG-only Pillow gate, exercises baseline and progressive files, and tests truncated copies of two actual image fixtures. It is a decoder correctness check, not a complete hostile-upload security boundary.

Two real fixtures

These are current public examples from the GPT Image 2 prompt workspace. They are two separate generated pictures, not a before-and-after edit. Their public source PNGs were decoded and saved locally as JPEGs at quality 93 for this exercise. Each JPEG is 1024 × 1024. No generation was run. The visible logos and lettering are image content, not evidence of brand affiliation or product accuracy.

The sneaker source prompt describes a floating packshot on a pastel background. The headphone source asks for a rim-lit product hero with negative space. Those briefs explain the images; the decoder test does not depend on their subject matter.

Make the acceptance contract explicit

Accept JPEG bytes only, with an example 8 MiB byte budget and 20-million-pixel budget. Require Pillow's permissive truncated-image flag to remain off. Decode all pixels and return an independent RGB image that remains usable after the input buffer closes.

Pillow documents Image.open() as lazy. Its Image reference distinguishes verification from pixel loading, and the file-format documentation describes the truncated-JPEG flag. Reopen a file if you need to load it after verify(); this gate simply loads on the first open.

Save decode_gate.py:

from io import BytesIO
from PIL import Image, ImageFile, UnidentifiedImageError

def decode_jpeg(data: bytes, max_pixels: int = 20_000_000) -> Image.Image:
    if ImageFile.LOAD_TRUNCATED_IMAGES:
        raise RuntimeError('strict worker must not allow truncated images')
    if not data or len(data) > 8 * 1024 * 1024:
        raise ValueError('empty file or byte limit exceeded')
    try:
        with Image.open(BytesIO(data), formats=['JPEG']) as image:
            width, height = image.size
            if width * height > max_pixels:
                raise ValueError('pixel limit exceeded')
            image.load()
            return image.convert('RGB').copy()
    except (OSError, SyntaxError, UnidentifiedImageError) as exc:
        raise ValueError('JPEG pixel decode failed') from exc

The flag check deliberately refuses a permissive worker configuration. It does not toggle a process-wide setting around each request, which would be unsafe when other threads share the decoder. Run this in a worker whose configuration you control.

Exercise truncation and valid formats

Save test_decode_gate.py alongside the implementation:

import unittest
from io import BytesIO
from PIL import Image, ImageFile
from decode_gate import decode_jpeg

def jpeg(progressive=False):
    out=BytesIO()
    Image.effect_noise((64, 64), 70).convert('RGB').save(out, 'JPEG', progressive=progressive)
    return out.getvalue()

class DecodeTests(unittest.TestCase):
    def test_valid_baseline_and_progressive(self):
        for progressive in (False, True):
            with self.subTest(progressive=progressive):
                result=decode_jpeg(jpeg(progressive));self.assertEqual(result.size,(64,64));result.thumbnail((16,16));self.assertEqual(result.size,(16,16))
    def test_cut_scan_data(self):
        for progressive in (False, True):
            data=jpeg(progressive)
            with self.subTest(progressive=progressive),self.assertRaises(ValueError):decode_jpeg(data[:len(data)//2])
    def test_missing_end_marker(self):
        with self.assertRaises(ValueError):decode_jpeg(jpeg()[:-2])
    def test_reject_non_jpeg(self):
        out=BytesIO();Image.new('RGB',(2,2)).save(out,'PNG')
        with self.assertRaises(ValueError):decode_jpeg(out.getvalue())
    def test_pixel_budget(self):
        with self.assertRaisesRegex(ValueError,'pixel limit'):decode_jpeg(jpeg(),100)
    def test_permissive_global_flag(self):
        original=ImageFile.LOAD_TRUNCATED_IMAGES
        try:
            ImageFile.LOAD_TRUNCATED_IMAGES=True
            with self.assertRaises(RuntimeError):decode_jpeg(jpeg())
        finally:ImageFile.LOAD_TRUNCATED_IMAGES=original

if __name__=='__main__':unittest.main()

Install Pillow in an isolated environment and run:

python -m pip install Pillow
python -m unittest -v test_decode_gate.py

All six tests passed in the executed environment, including baseline/progressive subcases, a missing end marker, non-JPEG input, the pixel budget and the permissive-flag check. The small noise images are test fixtures only, not article illustrations.

Reproduce the actual-file failure

Save the two displayed JPEGs as cover.jpg and workspace.jpg, then run:

from io import BytesIO
from pathlib import Path
from PIL import Image
from decode_gate import decode_jpeg

for name in ['cover.jpg', 'workspace.jpg']:
    data = Path(name).read_bytes()
    print(name, 'complete', decode_jpeg(data).size)
    cut = data[:len(data) // 2]
    with Image.open(BytesIO(cut)) as image:
        image.verify()
    print(name, 'header verification returned')
    try:
        decode_jpeg(cut)
    except ValueError as error:
        print(name, 'full decode rejected:', error)

For both actual fixtures, the complete file decoded to (1024, 1024). The half-file copy passed verify() but failed the full decode with JPEG pixel decode failed. This is a measured result for these files and Pillow build, not a claim that every truncated JPEG behaves identically.

Keep decoding separate from other policies

Enforce a streaming request limit before buffering an upload: this function sees bytes only after they exist. Add your application's isolation, resource limits, metadata policy and output encoding rules. Do not mistake successful decoding for malware scanning, authenticity verification or a guarantee that the image is suitable for publication. If you need a thumbnail, call thumbnail() on the returned image and save to a new controlled destination.

The inspected Voor page selected GPT Image 2 with Prompt, Reference images, Mask and Generate. On September 23, the visible selection was 3:4, one output and Low quality, with 5 credits and Public · watermarked. Uploads required sign-in; a signed-out Generate attempt reaches sign-in. These current controls do not establish the settings that produced the square source examples.

To obtain another ordinary image fixture, open the generator and inspect the current quote. The decoder and tests work independently of Voor and require no paid generation.

AI disclosure: this article and code were prepared by an automated assistant. The tests and both complete/truncated fixture checks were executed.

DEV Community