PaddlePaddle/PaddleOCR · error · InvalidRequestError

PaddleOCR-VL models require PaddleOCRVLOptions.

Error message

PaddleOCR-VL models require PaddleOCRVLOptions.

What it means

Raised as InvalidRequestError by resolve_document_options() when the model is a PaddleOCR-VL model but options is not a PaddleOCRVLOptions instance. VL models only accept their own options type; passing PPStructureV3Options or a bare DocParsingOptions is rejected before the request is built.

Source

Thrown at paddleocr/_api_client/_core.py:83

def resolve_model(model: Union[Model, str]) -> Model:
    if isinstance(model, Model):
        return model
    try:
        return Model(model)
    except ValueError as e:
        raise InvalidRequestError(f"Unsupported model: {model}") from e


def resolve_document_options(
    model: Model, options: Optional[DocParsingOptions]
) -> DocParsingOptions:
    if options is not None:
        if model == Model.PP_STRUCTURE_V3 and not isinstance(
            options, PPStructureV3Options
        ):
            raise InvalidRequestError("PP-StructureV3 requires PPStructureV3Options.")
        if is_vl_model(model) and not isinstance(options, PaddleOCRVLOptions):
            raise InvalidRequestError("PaddleOCR-VL models require PaddleOCRVLOptions.")
        return options
    if model == Model.PP_STRUCTURE_V3:
        return PPStructureV3Options()
    return PaddleOCRVLOptions()


def job_id_for_task(job: Union[Job, str], task: str) -> str:
    if isinstance(job, str):
        return job
    if job.task != task:
        raise InvalidRequestError(
            f"Job task mismatch: expected {task}, got {job.task}."
        )
    if task == "ocr" and not is_ocr_model(job.model):
        raise InvalidRequestError(f"Job model is not an OCR model: {job.model}.")
    if task == "document_parsing" and not is_document_parsing_model(job.model):
        raise InvalidRequestError(
            f"Job model is not a document parsing model: {job.model}."

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Use PaddleOCRVLOptions() with VL models.
2. Or pass options=None and let the default PaddleOCRVLOptions() be applied.
3. Add an assertion or helper mapping model -> options class.

Example fix

# before
job = client.parse_document(file_path="a.pdf", model="PaddleOCR-VL", options=PPStructureV3Options())

# after
from paddleocr._api_client.options import PaddleOCRVLOptions
job = client.parse_document(file_path="a.pdf", model="PaddleOCR-VL", options=PaddleOCRVLOptions())

from paddleocr._api_client.models import is_vl_model
from paddleocr._api_client.options import PaddleOCRVLOptions

def vl_options_ok(model, options) -> bool:
    return not is_vl_model(model) or isinstance(options, PaddleOCRVLOptions)

When it happens

Trigger: Calling document parsing with a VL model (per is_vl_model) and options=PPStructureV3Options() or another DocParsingOptions subclass.

Common situations: Reusing PP-StructureV3 options when switching to a VL model, or constructing a generic options object because the VL-specific class was not discovered.

Related errors

• PP-StructureV3 requires PPStructureV3Options.
• Unsupported OCR model: {model}
• Unsupported document parsing model: {model}
• Unsupported model: {model}
• Job model is not an OCR model: {job.model}.

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