{"record":{"id":"ef5995ac823e311c","repo":"PaddlePaddle/PaddleOCR","slug":"name-and-new-name-are-mutually-exclusive","errorCode":null,"errorMessage":"`{name}` and `{new_name}` are mutually exclusive.","messagePattern":"`(.+?)` and `(.+?)` are mutually exclusive\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"paddleocr/_pipelines/ocr.py","lineNumber":164,"sourceCode":"            \"text_det_limit_type\": text_det_limit_type,\n            \"text_det_thresh\": text_det_thresh,\n            \"text_det_box_thresh\": text_det_box_thresh,\n            \"text_det_unclip_ratio\": text_det_unclip_ratio,\n            \"text_det_input_shape\": text_det_input_shape,\n            \"text_rec_score_thresh\": text_rec_score_thresh,\n            \"return_word_box\": return_word_box,\n            \"text_rec_input_shape\": text_rec_input_shape,\n        }\n        base_params = {}\n        for name, val in kwargs.items():\n            if name in _DEPRECATED_PARAM_NAME_MAPPING:\n                new_name = _DEPRECATED_PARAM_NAME_MAPPING[name]\n                warn_deprecated_param(name, new_name)\n                assert (\n                    new_name in params\n                ), f\"{repr(new_name)} is not a valid parameter name.\"\n                if params[new_name] is not None:\n                    raise ValueError(\n                        f\"`{name}` and `{new_name}` are mutually exclusive.\"\n                    )\n                params[new_name] = val\n            else:\n                base_params[name] = val\n\n        self._params = params\n\n        super().__init__(**base_params)\n\n    @property\n    def _paddlex_pipeline_name(self):\n        return \"OCR\"\n\n    def predict_iter(\n        self,\n        input,\n        *,","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr/_pipelines/ocr.py#L146-L182","documentation":"PaddleOCR's constructor accepts deprecated parameter names (mapped via _DEPRECATED_PARAM_NAME_MAPPING, e.g. det_model_dir -> text_detection_model_dir, use_angle_cls -> use_textline_orientation). If you pass BOTH the deprecated name and its modern replacement, and the modern one is not None, it raises ValueError because the two would conflict. A deprecation warning is emitted first, then the conflict is detected.","triggerScenarios":"PaddleOCR(use_angle_cls=True, use_textline_orientation=True), PaddleOCR(det_model_dir='...', text_detection_model_dir='...'), or any pair in the mapping such as rec_batch_num together with text_recognition_batch_size where the new-name value is set.","commonSituations":"Migrating old sample code incrementally and ending up with both old and new kwargs; config files that accumulate options across paddleocr upgrades; tutorials mixing v2.x and v3.x parameter styles.","solutions":["Delete the deprecated parameter and keep only the modern one (see _DEPRECATED_PARAM_NAME_MAPPING for the exact rename table).","If the modern param is at its default None, passing only the deprecated name still works — so just drop one of the two.","Grep your config for the old names (det_model_dir, det_db_thresh, use_angle_cls, cls_model_dir, rec_batch_num, etc.) and migrate them."],"exampleFix":"# before\nocr = PaddleOCR(use_angle_cls=True, use_textline_orientation=True)  # ValueError\n# after\nocr = PaddleOCR(use_textline_orientation=True)","handlingStrategy":"validation","validationCode":"from paddleocr._pipelines.ocr import _DEPRECATED_PARAM_NAME_MAPPING\n\ndef strip_deprecated_conflicts(cfg: dict) -> dict:\n    cfg = dict(cfg)\n    for old, new in _DEPRECATED_PARAM_NAME_MAPPING.items():\n        if old in cfg and cfg.get(new) is not None:\n            del cfg[old]  # prefer the modern name\n    return cfg","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Migrate configs fully to the new parameter names in one pass","Never carry both a name and its rename in shared config dicts","Treat DeprecationWarnings as errors locally to catch leftover old names early"],"tags":["ocr","deprecated-params","migration","config","valueerror"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}