{"record":{"id":"8cce37cc2cf5f4a2","repo":"PaddlePaddle/PaddleOCR","slug":"a-dependency-error-occurred-during-predictor-creat","errorCode":null,"errorMessage":"A dependency error occurred during predictor creation. Please refer to the installation documentation to ensure all required dependencies are installed.","messagePattern":"A dependency error occurred during predictor creation\\. Please refer to the installation documentation to ensure all required dependencies are installed\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"paddleocr/_models/base.py","lineNumber":80,"sourceCode":"\n    @classmethod\n    @abc.abstractmethod\n    def get_cli_subcommand_executor(cls):\n        raise NotImplementedError\n\n    def _get_extra_paddlex_predictor_init_args(self):\n        return {}\n\n    def _create_paddlex_predictor(self):\n        kwargs = prepare_common_init_args(self._model_name, self._common_args)\n        kwargs = {**self._get_extra_paddlex_predictor_init_args(), **kwargs}\n        # Should we check model names?\n        try:\n            return create_predictor(\n                model_name=self._model_name, model_dir=self._model_dir, **kwargs\n            )\n        except DependencyError as e:\n            raise RuntimeError(\n                \"A dependency error occurred during predictor creation. Please refer to the installation documentation to ensure all required dependencies are installed.\"\n            ) from e\n\n\nclass PredictorCLISubcommandExecutor(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        subparser.add_argument(\"--model_name\", type=str, help=\"Name of the model.\")\n        subparser.add_argument(\n            \"--model_dir\", type=str, help=\"Directory where the model is stored.\"\n        )\n        add_common_cli_opts(","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr/_models/base.py#L62-L98","documentation":"BaseModel._create_paddlex_predictor wraps paddlex's DependencyError in a RuntimeError when create_predictor fails because optional runtime dependencies for the specific model are missing. The original DependencyError is chained (`from e`), so the full cause is visible in the traceback. It means the PaddleX/PaddleOCR installation is incomplete for that model, not that the code is wrong.","triggerScenarios":"Constructing any paddleocr model class (paddleocr._models.base.BaseModel subclasses, e.g. TextDetection, TextRecognition, VL recognition models) in a Python env where paddlex or its model-specific extras (paddlepaddle GPU build, opencv,rapid-json deps, encryption deps, etc.) are not installed.","commonSituations":"Installing paddleocr with a minimal pip install and then instantiating models; upgrading paddleocr to a version requiring a newer paddlex; CPU-only paddlepaddle while the model/predictor needs different extras; Docker images trimmed of optional wheels.","solutions":["Inspect the chained original exception (`raise ... from e`) in the traceback to identify the exact missing package.","Reinstall/complete the dependency: pip install paddlex (or the version pinned by your paddleocr release), plus any model-specific extra it names.","Align versions: upgrade/downgrade paddlepaddle and paddlex to the combination documented for your paddleocr version.","Verify in a clean virtual environment per the official installation docs before rerunning."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import importlib.util\n\ndef paddlex_available() -> bool:\n    return importlib.util.find_spec('paddlex') is not None","typeGuard":null,"tryCatchPattern":"try:\n    model = SomeModel()\nexcept RuntimeError as e:\n    if 'dependency error' in str(e).lower() and e.__cause__ is not None:\n        missing = e.__cause__  # the original DependencyError names the package\n        sys.exit(f\"Install missing dependency then retry: {missing}\")\n    raise","preventionTips":["Pin exact versions of paddleocr, paddlex and paddlepaddle in requirements","Install into a fresh venv per the official docs rather than layering installs","Smoke-test model construction at container build time, not at first inference"],"tags":["dependency","paddlex","environment","predictor","runtimeerror"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}