{"record":{"id":"c1f998aef271fb85","repo":"ocrmypdf/OCRmyPDF","slug":"could-not-load-plugin-from-plugin-path","errorCode":null,"errorMessage":"Could not load plugin from {plugin_path}","messagePattern":"Could not load plugin from (.+?)","errorType":"error_code","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/ocrmypdf/_plugin_manager.py","lineNumber":111,"sourceCode":"            for module_info in sorted(\n                pkgutil.iter_modules(ocrmypdf.builtin_plugins.__path__)\n            ):\n                name = f'ocrmypdf.builtin_plugins.{module_info.name}'\n                module = importlib.import_module(name)\n                self._pm.register(module)\n\n        # 2. Register setuptools plugins\n        self._pm.load_setuptools_entrypoints('ocrmypdf')\n\n        # 3. Register plugins specified on command line\n        for plugin in self._plugins:\n            if isinstance(plugin, Path) or plugin.endswith('.py'):\n                # Import by filename\n                plugin_path = Path(plugin)\n                module_name = plugin_path.stem\n                spec = importlib.util.spec_from_file_location(module_name, plugin_path)\n                if spec is None or spec.loader is None:\n                    raise ImportError(f'Could not load plugin from {plugin_path}')\n                module = importlib.util.module_from_spec(spec)\n                sys.modules[module_name] = module\n                spec.loader.exec_module(module)\n            else:\n                # Import by dotted module name\n                module = importlib.import_module(plugin)\n            self._pm.register(module)\n\n    # =========================================================================\n    # Type-safe hook methods\n    # =========================================================================\n\n    # --- firstresult hooks ---\n\n    def get_logging_console(self) -> Handler | None:\n        \"\"\"Returns a custom logging handler for progress bar compatibility.\"\"\"\n        return self._pm.hook.get_logging_console()\n","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/ocrmypdf/OCRmyPDF/blob/5074a0b0e109362422b768fd271ed84bf717c4ec/src/ocrmypdf/_plugin_manager.py#L93-L129","documentation":"Raised by the plugin manager when a plugin given as a .py file path cannot be imported — importlib.util.spec_from_file_location returns no spec/loader, meaning the file doesn't exist, isn't a loadable Python module, or the path is wrong.","triggerScenarios":"Passing --plugin some_path.py that doesn't exist or isn't valid Python; happens during OcrMyPDF plugin setup at initialization.","commonSituations":"Typo in the plugin path, moved/renamed plugin file, plugin with syntax errors so severe the spec fails, or relative path resolved from the wrong working directory.","solutions":["Verify the plugin path exists and is absolute","Check the file is valid Python (python -c 'import ast; ast.parse(open(\"plugin.py\").read())')","Use a dotted module name instead if the plugin is installed as a package"],"exampleFix":"# before\nocrmypdf --plugin plugins/myplug.py in.pdf out.pdf\n# after\nocrmypdf --plugin /abs/path/plugins/myplugin.py in.pdf out.pdf","handlingStrategy":"validation","validationCode":"from pathlib import Path\np = Path(plugin_arg)\nif p.suffix == '.py' and not (p.is_file() and p.read_text().count('') >= 0):\n    raise SystemExit(f'plugin not found: {p.resolve()}')","typeGuard":null,"tryCatchPattern":"catch ImportError, log plugin path, skip plugin and continue if optional","preventionTips":["Resolve plugin paths to absolute paths at CLI-construction time"],"tags":["ocr","ocrmypdf","plugins","import"],"backgroundTag":"plugin-load-failure","analyzedSha":"5074a0b0e109362422b768fd271ed84bf717c4ec","analyzedAt":"2026-08-27T11:57:38.523Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}