PaddlePaddle/PaddleOCR · error · ValueError

Invalid OCR version: {ocr_version}. Supported values are {_S

Error message

Invalid OCR version: {ocr_version}. Supported values are {_SUPPORTED_OCR_VERSIONS}.

What it means

PPStructureV3's constructor validates ocr_version against its own _SUPPORTED_OCR_VERSIONS list, which is ['PP-OCRv3','PP-OCRv4','PP-OCRv5'] — notably shorter than the PaddleOCR pipeline's list (which adds PP-OCRv6). Passing an unrecognized or PP-OCRv6 version here raises ValueError before models load.

Source

Thrown at paddleocr/_pipelines/pp_structurev3.py:104

        formula_recognition_model_name=None,
        formula_recognition_model_dir=None,
        formula_recognition_batch_size=None,
        use_doc_orientation_classify=None,
        use_doc_unwarping=None,
        use_textline_orientation=None,
        use_seal_recognition=None,
        use_table_recognition=None,
        use_formula_recognition=None,
        use_chart_recognition=None,
        use_region_detection=None,
        format_block_content=None,
        markdown_ignore_labels=None,
        lang=None,
        ocr_version=None,
        **kwargs,
    ):
        if ocr_version is not None and ocr_version not in _SUPPORTED_OCR_VERSIONS:
            raise ValueError(
                f"Invalid OCR version: {ocr_version}. Supported values are {_SUPPORTED_OCR_VERSIONS}."
            )

        if all(
            map(
                lambda p: p is None,
                (
                    text_detection_model_name,
                    text_detection_model_dir,
                    text_recognition_model_name,
                    text_recognition_model_dir,
                ),
            )
        ):
            if lang is not None or ocr_version is not None:
                det_model_name, rec_model_name = self._get_ocr_model_names(
                    lang, ocr_version
                )

View on GitHub (pinned to 2661c7c0ef)

Solutions

Use 'PP-OCRv3', 'PP-OCRv4', or 'PP-OCRv5' (exact case), or omit ocr_version for the default.
If you specifically need PP-OCRv6 text models inside document parsing, pass them explicitly via text_detection_model_name / text_recognition_model_name instead of ocr_version.
Keep per-pipeline config instead of one shared ocr_version value.

Example fix

# before
pipe = PPStructureV3(ocr_version='PP-OCRv6')  # ValueError in this pipeline
# after
pipe = PPStructureV3(ocr_version='PP-OCRv5')

Defensive patterns

Strategy: validation

Validate before calling

from paddleocr._pipelines.pp_structurev3 import _SUPPORTED_OCR_VERSIONS as STRUCT_VERS

def valid_struct_ocr_version(v) -> bool:
    return v is None or v in STRUCT_VERS  # ['PP-OCRv3','PP-OCRv4','PP-OCRv5']

Prevention

Do not share one ocr_version value across pipelines; each validates its own list
PP-OCRv6 is rejected here even though PaddleOCR accepts it
Validate config against the specific pipeline module's constants

When it happens

Trigger: PPStructureV3(ocr_version='PP-OCRv6') (valid for PaddleOCR but NOT here), PPStructureV3(ocr_version='pp-ocrv4') (case-sensitive), or 'PP-OCRv2'.

Common situations: Sharing one config dict between PaddleOCR and PPStructureV3 pipelines; assuming all pipelines accept the same version list; copying PP-OCRv6 settings from OCR docs into a structure pipeline.

Related errors

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