PaddlePaddle/PaddleOCR · error · InvalidRequestError

Unsupported model: {model}

Error message

Unsupported model: {model}

What it means

Raised as InvalidRequestError by resolve_model() when the argument is a string that does not match any Model enum value (Model(model) raises ValueError, chained here), or when it is neither a Model instance nor a coercible string. It is the generic model-resolution failure behind the OCR/document-specific variants.

Source

Thrown at paddleocr/_api_client/_core.py:71

    if not is_ocr_model(resolved):
        raise InvalidRequestError(f"Unsupported OCR model: {model}")
    return resolved


def resolve_document_model(model: Union[Model, str]) -> Model:
    resolved = resolve_model(model)
    if not is_document_parsing_model(resolved):
        raise InvalidRequestError(f"Unsupported document parsing model: {model}")
    return resolved


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()

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Check the Model enum in this package version for the exact accepted names.
2. Fix casing/whitespace in the configured model string.
3. If the name was removed in an upgrade, migrate to the current equivalent model.
4. Prefer passing the Model enum member instead of a raw string.

Example fix

# before
result = client.ocr(file_path="a.png", model="ppocrv5")

# after
from paddleocr._api_client.models import Model
result = client.ocr(file_path="a.png", model=Model.PP_OCRv5)

from paddleocr._api_client.models import Model

def valid_model(name: str) -> bool:
    try:
        Model(name)
        return True
    except ValueError:
        return False

assert valid_model(configured_model), f"unknown model {configured_model!r}"

from paddleocr._api_client.models import Model

def is_known_model(value) -> bool:
    if isinstance(value, Model):
        return True
    try:
        Model(value)
        return True
    except ValueError:
        return False

When it happens

Trigger: Passing model="my-model", a typo like "pp-ocrv4 " (case/whitespace), a deprecated model name removed in this version, or a non-string non-Model object.

Common situations: Version upgrades that rename or remove Model members, config files carrying stale names, or dynamically built strings with wrong casing.

Related errors

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

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