PaddlePaddle/PaddleOCR · error · ValueError

Invalid backend for the VL recognition module: {vl_rec_backe

Error message

Invalid backend for the VL recognition module: {vl_rec_backend}. Supported values are {_SUPPORTED_VL_BACKENDS}.

What it means

The PaddleOCR-VL constructor validates the VL recognition backend name against _SUPPORTED_VL_BACKENDS and raises ValueError for unknown values. The check is skipped when vl_rec_backend is None (default), so it only fires when an explicit unsupported backend string is supplied.

Source

Thrown at paddleocr/_pipelines/paddleocr_vl.py:76

        use_doc_orientation_classify=None,
        use_doc_unwarping=None,
        use_layout_detection=None,
        use_chart_recognition=None,
        use_seal_recognition=None,
        use_ocr_for_image_block=None,
        format_block_content=None,
        merge_layout_blocks=None,
        markdown_ignore_labels=None,
        use_queues=None,
        **kwargs,
    ):
        if pipeline_version not in _AVAILABLE_PIPELINE_VERSIONS:
            raise ValueError(
                f"Invalid pipeline version: {pipeline_version}. Supported versions are {_AVAILABLE_PIPELINE_VERSIONS}."
            )

        if vl_rec_backend is not None and vl_rec_backend not in _SUPPORTED_VL_BACKENDS:
            raise ValueError(
                f"Invalid backend for the VL recognition module: {vl_rec_backend}. Supported values are {_SUPPORTED_VL_BACKENDS}."
            )

        params = locals().copy()
        params.pop("self")
        params.pop("pipeline_version")
        params.pop("kwargs")
        self._params = params
        self.pipeline_version = pipeline_version

        super().__init__(**kwargs)

    @property
    def _paddlex_pipeline_name(self):
        if self.pipeline_version == "v1":
            return "PaddleOCR-VL"
        elif self.pipeline_version == "v1.5":
            return "PaddleOCR-VL-1.5"

View on GitHub (pinned to 2661c7c0ef)

Solutions

Use one of the supported backends — inspect paddleocr._pipelines.paddleocr_vl._SUPPORTED_VL_BACKENDS for your install and pass an exact entry.
Omit vl_rec_backend to use the default backend.
If you need a specific engine (e.g. TensorRT), configure it through the correct backend's own options after choosing a supported backend value.

Example fix

# before
pipe = PaddleOCRVL(vl_rec_backend='tensorrt')  # ValueError
# after
from paddleocr._pipelines.paddleocr_vl import _SUPPORTED_VL_BACKENDS
pipe = PaddleOCRVL(vl_rec_backend=_SUPPORTED_VL_BACKENDS[0])

Defensive patterns

Strategy: validation

Validate before calling

from paddleocr._pipelines.paddleocr_vl import _SUPPORTED_VL_BACKENDS

def valid_vl_backend(b) -> bool:
    return b is None or b in _SUPPORTED_VL_BACKENDS

Prevention

Pick backends from _SUPPORTED_VL_BACKENDS, not engine nicknames like 'tensorrt'
Omit vl_rec_backend unless you specifically need a non-default backend
Re-check the backend list after package upgrades

When it happens

Trigger: PaddleOCRVL(vl_rec_backend='trt'), vl_rec_backend='paddle' when the installed release only supports other names, or any typo/case variant of a supported backend string.

Common situations: Passing inference-engine nicknames ('onnx', 'tensorrt', 'gpu') that are not backend identifiers in this API; backend names changing across paddleocr versions; copy-pasting config between versions.

Related errors

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