PaddlePaddle/PaddleOCR · error · InvalidRequestError

min_pixels must be greater than 0.

Error message

min_pixels must be greater than 0.

What it means

InvalidRequestError raised by _validate_vl_options when PaddleOCRVLOptions.min_pixels is <= 0. min_pixels bounds the minimum processed image size for the VL model and must be a positive pixel count.

Source

Thrown at paddleocr/_api_client/models.py:194

            continue
        if field.name == "extra_options":
            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 min_pixels to a positive integer pixel area
2. Leave it None for the default
3. Ensure min_pixels <= max_pixels (a follow-up check enforces this)

Example fix

# before
options = PaddleOCRVLOptions(min_pixels=0)
# after
options = PaddleOCRVLOptions(min_pixels=448 * 448)

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

from paddleocr._api_client.errors import InvalidRequestError

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

When it happens

Trigger: PaddleOCRVLOptions(min_pixels=0) or negative; passing a dimension (e.g. 448) where a pixel area is expected, or vice versa producing 0 through unit confusion.

Common situations: Tuning image resolution knobs copied from model configs where the value is expressed as pixels = side*side; zero used to mean 'no minimum'.

Related errors

• max_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/64aaec093001a858. Report an issue: GitHub.