{"record":{"id":"fef32ccc3267771d","repo":"PaddlePaddle/PaddleOCR","slug":"a-dependency-error-occurred-during-pipeline-creati","errorCode":null,"errorMessage":"A dependency error occurred during pipeline creation. Please refer to the installation documentation to ensure all required dependencies are installed.","messagePattern":"A dependency error occurred during pipeline creation\\. Please refer to the installation documentation to ensure all required dependencies are installed\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"paddleocr/_pipelines/base.py","lineNumber":107,"sourceCode":"\n    def _get_merged_paddlex_config(self):\n        if self._paddlex_config is None:\n            config = load_pipeline_config(self._paddlex_pipeline_name)\n        elif isinstance(self._paddlex_config, str):\n            config = load_pipeline_config(self._paddlex_config)\n        else:\n            config = self._paddlex_config\n\n        overrides = self._get_paddlex_config_overrides()\n\n        return _merge_dicts(config, overrides)\n\n    def _create_paddlex_pipeline(self):\n        kwargs = prepare_common_init_args(None, self._common_args)\n        try:\n            return create_pipeline(config=self._merged_paddlex_config, **kwargs)\n        except DependencyError as e:\n            raise RuntimeError(\n                \"A dependency error occurred during pipeline creation. Please refer to the installation documentation to ensure all required dependencies are installed.\"\n            ) from e\n\n\nclass PipelineCLISubcommandExecutor(CLISubcommandExecutor):\n    @property\n    @abc.abstractmethod\n    def subparser_name(self):\n        raise NotImplementedError\n\n    def add_subparser(self, subparsers):\n        subparser = subparsers.add_parser(name=self.subparser_name)\n        self._update_subparser(subparser)\n        add_common_cli_opts(\n            subparser,\n            default_enable_hpi=_DEFAULT_ENABLE_HPI,\n            allow_multiple_devices=True,\n        )","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr/_pipelines/base.py#L89-L125","documentation":"BasePipeline._create_paddlex_pipeline wraps paddlex's DependencyError in a RuntimeError when create_pipeline fails because required optional dependencies for the pipeline are not installed. The original cause is chained in the traceback. This is the pipeline-level twin of the predictor-level error in _models/base.py and always indicates an incomplete environment rather than bad arguments.","triggerScenarios":"Instantiating any paddleocr pipeline (PaddleOCR, PPStructureV3, PaddleOCRVL, PPChatOCRv3, ...) via constructor or CLI in an environment where paddlex or pipeline-specific extras (paddlepaddle, opencv, pdf rendering libs, etc.) are missing or version-mismatched.","commonSituations":"Fresh pip install of paddleocr without its dependency group; GPU paddlepaddle absent on a CUDA machine; paddlex upgraded independently of paddleocr and no longer matching; slim Docker images.","solutions":["Read the chained original DependencyError in the traceback to find the exact missing distribution.","Install the missing packages: pip install paddlex and/or the extras the message names (e.g. paddlepaddle-gpu).","Use the dependency set from the official installation docs for your paddleocr version (e.g. pip install 'paddleocr[all]' or the documented serving extras).","Reproduce in a fresh venv to rule out conflicting site-packages."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import importlib.util\n\ndef pipeline_deps_ok() -> bool:\n    return all(importlib.util.find_spec(m) is not None for m in ('paddlex', 'paddle'))","typeGuard":null,"tryCatchPattern":"try:\n    pipe = PaddleOCR()\nexcept RuntimeError as e:\n    if 'dependency error' in str(e).lower() and e.__cause__ is not None:\n        print('Missing dependency:', e.__cause__)\n        print('Fix: pip install paddlex / the package named above')\n        raise SystemExit(1)\n    raise","preventionTips":["Use the documented dependency group for your pipeline (e.g. paddleocr[all])","Verify paddlex/paddlepaddle version compatibility matrix before upgrading either","Run a pipeline construction smoke test in CI for the exact image you deploy"],"tags":["dependency","paddlex","pipeline","environment","runtimeerror"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}