PaddlePaddle/PaddleOCR · error · InvalidRequestError

Unsupported OCR model: {model}

Error message

Unsupported OCR model: {model}

What it means

Raised as InvalidRequestError by resolve_ocr_model() when the resolved model is not in the OCR model set. The model may be a valid Model enum member (e.g. a document-parsing or VL model) but is being passed to an OCR-specific entry point. Resolution happens before any request is sent.

Source

Thrown at paddleocr/_api_client/_core.py:54

def validate_input_source(file_url: Optional[str], file_path: Optional[str]) -> None:
    if not file_url and not file_path:
        raise InvalidRequestError("Either file_url or file_path is required.")
    if file_url and file_path:
        raise InvalidRequestError("file_url and file_path are mutually exclusive.")


def default_payload(model: Model) -> dict:
    if is_ocr_model(model):
        return OCROptions().to_payload()
    return resolve_document_options(model, None).to_payload()


def resolve_ocr_model(model: Union[Model, str]) -> Model:
    resolved = resolve_model(model)
    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

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Use an OCR model (check the Model enum members satisfying is_ocr_model) for OCR calls.
2. If you intended document parsing or VL, call the document-parsing entry point instead.
3. List valid options via the Model enum to confirm naming.

Example fix

# before
result = client.ocr(file_path="a.png", model="PP-StructureV3")

# after
result = client.ocr(file_path="a.png", model="PP-OCRv5")  # or use the document-parsing API

from paddleocr._api_client.models import is_ocr_model, resolve_model

def usable_for_ocr(model) -> bool:
    try:
        return is_ocr_model(resolve_model(model))
    except Exception:
        return False

from paddleocr._api_client.errors import InvalidRequestError
try:
    result = client.ocr(file_path=p, model=model)
except InvalidRequestError as e:
    if "Unsupported OCR model" in str(e):
        model = "PP-OCRv5"  # fall back to a known OCR model

When it happens

Trigger: Calling an OCR method with model='PP-StructureV3' or a VL model string/enum, or any string that resolves to a non-OCR Model.

Common situations: Confusing the OCR and document-parsing APIs after a version upgrade that split them, or reusing a configured model name across different endpoints.

Related errors

• Unsupported document parsing model: {model}
• Unsupported 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/f6b75426f6cb2131. Report an issue: GitHub.