squidfunk/mkdocs-material · error · PluginError

{e}

Error message

{e}

What it means

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.

Source

Thrown at src/plugins/group/plugin.py:86

    @event_priority(150)
    def on_config(self, config):
        if not self.config.enabled:
            return

        # Retrieve plugin collection from configuration
        option: Plugins = dict(config._schema)["plugins"]
        assert isinstance(option, Plugins)

        # Load all plugins in group
        self.plugins: dict[str, BasePlugin] = {}
        try:
            for name, plugin in self._load(option):
                self.plugins[name] = plugin

        # The plugin could not be loaded, likely because it's not installed or
        # misconfigured, so we raise a plugin error for a nicer error message
        except Exception as e:
            raise PluginError(str(e))

        # Patch order of plugin methods
        for events in option.plugins.events.values():
            self._patch(events, config)

        # Invoke `on_startup` event for plugins in group
        command = "serve" if self.is_serve else "build"
        for method in option.plugins.events["startup"]:
            plugin = self._get_plugin(method)

            # Ensure that we have a method bound to a plugin (and not a hook)
            if plugin and plugin in self.plugins.values():
                method(command = command, dirty = self.is_dirty)

    # -------------------------------------------------------------------------

    # Retrieve plugin instance for bound method or nothing
    def _get_plugin(self, method: Callable):

View on GitHub (pinned to e2136532f4)

Solutions

1. Read the wrapped message and fix the underlying cause — usually `pip install` the missing plugin package
2. Correct the plugin name/module path in the group configuration in mkdocs.yml
3. Verify plugin versions are compatible with your mkdocs-material version
4. If it's a custom plugin, run `python -c "import <module>"` to reproduce the import error

Example fix

# before (mkdocs.yml)
plugins:
  - group:
      plugins:
        - social   # not installed

// after
# pip install mkdocs-material[imaging]
plugins:
  - group:
      plugins:
        - social

import importlib, sys
plugins = ['social', 'search']  # names configured under group
missing = [p for p in plugins if importlib.util.find_spec(p) is None]
assert not missing, f"Plugins not installed: {missing}"

try:
    mkdocs.commands.build(config)
except PluginError as e:
    log.error(f"Group plugin failed to load a sub-plugin: {e}")
    raise SystemExit(1)

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• Relative path processor not registered
• Error reading filter configuration in '{key}': {e}
• Unknown shortcode: {type}
• Unknown type: {type}
• Couldn't find author '{id}'

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/ed7d854969022f23. Report an issue: GitHub.