PaddlePaddle/PaddleOCR · error · ValueError

Unknown argument

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.

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

• Conflicting values provided for
• Invalid engine: . Supported values are: .
• Invalid precision: . Supported values are: .
• model selection must define model_name.
• OCR model selection must define both detection and…

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

Appendix: 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)