PaddlePaddle/PaddleOCR · error · ValueError

Unknown argument: {name}

Error message

Unknown argument: {name}

What it means

ValueError raised by parse_common_args when kwargs contain a key that is not in the known set of common inference arguments (device, engine, engine_config, enable_hpi, use_tensorrt, precision, enable_mkldnn, mkldnn_cache_capacity, cpu_threads, enable_cinn). It catches typos and renamed parameters before pipeline construction.

Source

Thrown at paddleocr/_common_args.py:54

def parse_common_args(kwargs, *, default_enable_hpi):
    default_vals = {
        "device": DEFAULT_DEVICE,
        "engine": None,
        "engine_config": None,
        "enable_hpi": default_enable_hpi,
        "use_tensorrt": DEFAULT_USE_TENSORRT,
        "precision": DEFAULT_PRECISION,
        "enable_mkldnn": DEFAULT_ENABLE_MKLDNN,
        "mkldnn_cache_capacity": DEFAULT_MKLDNN_CACHE_CAPACITY,
        "cpu_threads": DEFAULT_CPU_THREADS,
        "enable_cinn": DEFAULT_USE_CINN,
    }

    unknown_names = kwargs.keys() - default_vals.keys()
    for name in unknown_names:
        raise ValueError(f"Unknown argument: {name}")

    kwargs = {**default_vals, **kwargs}

    if (
        kwargs["engine"] is not None
        and kwargs["engine"] not in SUPPORTED_INFERENCE_ENGINE_LIST
    ):
        raise ValueError(
            f"Invalid engine: {kwargs['engine']}. Supported values are: {SUPPORTED_INFERENCE_ENGINE_LIST}."
        )

    if kwargs["precision"] not in SUPPORTED_PRECISION_LIST:
        raise ValueError(
            f"Invalid precision: {kwargs['precision']}. Supported values are: {SUPPORTED_PRECISION_LIST}."
        )

    kwargs["use_pptrt"] = kwargs.pop("use_tensorrt")
    kwargs["pptrt_precision"] = kwargs.pop("precision")

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Check the spelling of every keyword against the error message (the first unknown name is reported)
2. Compare with the supported list: device, engine, engine_config, enable_hpi, use_tensorrt, precision, enable_mkldnn, mkldnn_cache_capacity, cpu_threads, enable_cinn
3. If the arg was renamed across versions, update it (e.g. use_tensorrt in this version, use_pptrt internally)
4. Move model/pipeline-specific options to the API that accepts them

Example fix

# before
ocr = PaddleOCR(devise='gpu')
# after
ocr = PaddleOCR(device='gpu')

from paddleocr._common_args import parse_common_args

KNOWN = {'device','engine','engine_config','enable_hpi','use_tensorrt','precision','enable_mkldnn','mkldnn_cache_capacity','cpu_threads','enable_cinn'}
unknown = set(user_kwargs) - KNOWN
if unknown:
    raise ValueError(f'unknown args: {sorted(unknown)}')

When it happens

Trigger: Calling PaddleOCR(..., devise='gpu') (typo), or passing arguments removed/renamed in the current version (e.g. use_tensorrt renamed to enable_tensorrt in an older/newer release), or passing model-specific kwargs into the common-arg parser.

Common situations: Upgrading paddleocr versions where argument names changed; copy-pasting kwargs from examples for a different version; passing pipeline-specific options at the wrong level.

Related errors

• worker mode does not support a custom fetch implementation.
• Conflicting values provided for ${label}: ${aliases.join(",
• ${modelRole} model selection must define model_name.
• OCR model selection must define both detection and recogniti
• worker must be a boolean or an options object.

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