{"record":{"id":"ed7d854969022f23","repo":"squidfunk/mkdocs-material","slug":"e","errorCode":null,"errorMessage":"{e}","messagePattern":"\\{e\\}","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/group/plugin.py","lineNumber":86,"sourceCode":"    @event_priority(150)\n    def on_config(self, config):\n        if not self.config.enabled:\n            return\n\n        # Retrieve plugin collection from configuration\n        option: Plugins = dict(config._schema)[\"plugins\"]\n        assert isinstance(option, Plugins)\n\n        # Load all plugins in group\n        self.plugins: dict[str, BasePlugin] = {}\n        try:\n            for name, plugin in self._load(option):\n                self.plugins[name] = plugin\n\n        # The plugin could not be loaded, likely because it's not installed or\n        # misconfigured, so we raise a plugin error for a nicer error message\n        except Exception as e:\n            raise PluginError(str(e))\n\n        # Patch order of plugin methods\n        for events in option.plugins.events.values():\n            self._patch(events, config)\n\n        # Invoke `on_startup` event for plugins in group\n        command = \"serve\" if self.is_serve else \"build\"\n        for method in option.plugins.events[\"startup\"]:\n            plugin = self._get_plugin(method)\n\n            # Ensure that we have a method bound to a plugin (and not a hook)\n            if plugin and plugin in self.plugins.values():\n                method(command = command, dirty = self.is_dirty)\n\n    # -------------------------------------------------------------------------\n\n    # Retrieve plugin instance for bound method or nothing\n    def _get_plugin(self, method: Callable):","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/group/plugin.py#L68-L104","documentation":"The `group` plugin loads its configured sub-plugins dynamically inside `on_config`. If loading any plugin fails for any reason (module not installed, bad option, import error), the original exception is caught and re-raised as a PluginError whose message is just the underlying exception text.","triggerScenarios":"`plugins.group` lists a plugin name that is not installed, a module path that doesn't exist, or a plugin whose constructor raises because of invalid options; also any ImportError raised while `self._load(option)` instantiates the sub-plugins.","commonSituations":"Forgetting to `pip install mkdocs-material[imaging]` or the package providing a custom plugin; typo in the plugin name in mkdocs.yml; version mismatch where a plugin option no longer exists; custom plugin code with an import-time bug.","solutions":["Read the wrapped message and fix the underlying cause — usually `pip install` the missing plugin package","Correct the plugin name/module path in the group configuration in mkdocs.yml","Verify plugin versions are compatible with your mkdocs-material version","If it's a custom plugin, run `python -c \"import <module>\"` to reproduce the import error"],"exampleFix":"# before (mkdocs.yml)\nplugins:\n  - group:\n      plugins:\n        - social   # not installed\n\n// after\n# pip install mkdocs-material[imaging]\nplugins:\n  - group:\n      plugins:\n        - social","handlingStrategy":"try-catch","validationCode":"import importlib, sys\nplugins = ['social', 'search']  # names configured under group\nmissing = [p for p in plugins if importlib.util.find_spec(p) is None]\nassert not missing, f\"Plugins not installed: {missing}\"\n","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs.commands.build(config)\nexcept PluginError as e:\n    log.error(f\"Group plugin failed to load a sub-plugin: {e}\")\n    raise SystemExit(1)\n","preventionTips":["Pin plugin packages in requirements.txt and install them before building","Verify each plugin name in the group config matches an installed package","Test `mkdocs build` in CI so missing plugins fail fast","Check plugin compatibility with your mkdocs-material version after upgrades"],"tags":["mkdocs","group-plugin","plugin-loading","dependency"],"backgroundTag":"plugin-load-failed","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}