PaddlePaddle/PaddleOCR · error · InvalidRequestError

max_pixels must be greater than 0.

Error message

max_pixels must be greater than 0.

What it means

InvalidRequestError raised by _validate_vl_options when PaddleOCRVLOptions.max_pixels is <= 0. max_pixels caps the processed image area for the VL model and must be positive.

Source

Thrown at paddleocr/_api_client/models.py:196

            payload.update(value)
        else:
            payload[snake_to_camel(field.name)] = value
    return payload


def _validate_vl_options(options: PaddleOCRVLOptions) -> None:
    if options.top_p is not None and not (0 < options.top_p <= 1):
        raise InvalidRequestError(
            "top_p must be greater than 0 and less than or equal to 1."
        )
    if options.temperature is not None and options.temperature < 0:
        raise InvalidRequestError("temperature must be greater than or equal to 0.")
    if options.repetition_penalty is not None and options.repetition_penalty <= 0:
        raise InvalidRequestError("repetition_penalty must be greater than 0.")
    if options.min_pixels is not None and options.min_pixels <= 0:
        raise InvalidRequestError("min_pixels must be greater than 0.")
    if options.max_pixels is not None and options.max_pixels <= 0:
        raise InvalidRequestError("max_pixels must be greater than 0.")
    if (
        options.min_pixels is not None
        and options.max_pixels is not None
        and options.min_pixels > options.max_pixels
    ):
        raise InvalidRequestError("min_pixels cannot be greater than max_pixels.")

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Set max_pixels to a positive pixel area (e.g. 16384*28*28-style limits from model configs)
2. Leave it None for the default

Example fix

# before
options = PaddleOCRVLOptions(max_pixels=0)
# after
options = PaddleOCRVLOptions(max_pixels=12845056)

if options.max_pixels is not None:
    assert options.max_pixels > 0, 'max_pixels must be positive pixel area'

from paddleocr._api_client.errors import InvalidRequestError

try:
    run(options)
except InvalidRequestError as e:
    if 'max_pixels' in str(e):
        options.max_pixels = None  # server default
    else:
        raise

When it happens

Trigger: PaddleOCRVLOptions(max_pixels=0) or a negative number; integer overflow or unit mistakes producing zero/negative values.

Common situations: Copy-pasting config where max_pixels is expressed in megapixels or side length; attempting to disable the cap with 0.

Related errors

• min_pixels must be greater than 0.
• min_pixels cannot be greater than max_pixels.
• Resource filename must not be empty.
• top_p must be greater than 0 and less than or equal to 1.
• temperature must be greater than or equal to 0.

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/bdd4bcbad6a056bc. Report an issue: GitHub.