What causes "Couldn't find layout '{name}'" in squidfunk/mkdocs-material?

Check the layout name against the built-in layouts documented for the installed mkdocs-material version (e.g. 'default', 'default/mini', 'embed', 'offset', 'excerpt', etc.).

squidfunk/mkdocs-material · error · PluginError

Couldn't find layout '{name}'

Error message

Couldn't find layout '{name}'

What it means

The social plugin renders social cards using a named layout defined via the plugin's `cards_layout` option. `_resolve_layout` looks up the requested name in the already-loaded `card_layouts` dict and throws this PluginError when the name is absent, meaning no built-in or user-registered layout matches.

Source

Thrown at src/plugins/social/plugin.py:800

                self.card_layouts[name] = layout
                self.card_variables[name] = []

                # Extract variables for each layer from layout
                for layer in layout.layers:
                    variables = _extract(layer, self.card_env, config)
                    self.card_variables[name].append(variables)

                    # Set default values for for layer size, if not given
                    for key, value in layer.size.items():
                        if value == 0:
                            layer.size[key] = layout.size[key]

            # Abort, since we're done
            break

        # Abort if the layout could not be resolved
        if name not in self.card_layouts:
            raise PluginError(f"Couldn't find layout '{name}'")

        # Return layout and variables
        return self.card_layouts[name], self.card_variables[name]

    # Resolve icon with given name - this function searches for the icon in all
    # known theme directories, including custom directories specified by the
    # author, which allows for using custom icons in cards. If the icon cannot
    # be resolved, the plugin must abort with an error.
    def _resolve_icon(self, name: str, config: MkDocsConfig):
        for base in config.theme.dirs:
            path = os.path.join(base, ".icons", f"{name}.svg")
            path = os.path.normpath(path)

            # Skip if icon does not exist and try next directory
            if not os.path.isfile(path):
                continue

            # Open and return icon

View on GitHub (pinned to e2136532f4)

Solutions

Check the layout name against the built-in layouts documented for the installed mkdocs-material version (e.g. 'default', 'default/mini', 'embed', 'offset', 'excerpt', etc.).
If using a custom layout, install/enable the plugin that registers it before the social plugin resolves it.
Fix YAML so `cards_layout` is nested under the social plugin's options in mkdocs.yml or under the page's `social` meta key.
Pin or upgrade mkdocs-material if the layout was renamed in a newer version.

Example fix

# before
plugins:
  - social:
      cards_layout: custum-big

# after
plugins:
  - social:
      cards_layout: custom:big  # or a valid built-in name like 'default'

Defensive patterns

Strategy: validation

Validate before calling

import mkdocs_social  # social plugin internals
# before building:
plugin = config.plugins['social']
if cards_layout_name not in plugin.card_layouts:
    raise SystemExit(f"Unknown cards_layout '{cards_layout_name}'. Known: {sorted(plugin.card_layouts)}")

Try / catch

from mkdocs.exceptions import PluginError
try:
    layout, variables = plugin._resolve_layout(name)
except PluginError as e:
    log.error(f"Bad cards_layout: {e}")
    layout, variables = plugin._resolve_layout('default')  # or abort

Prevention

Only reference layout names listed in the mkdocs-material docs for your installed version
Keep custom layout provider plugins installed and enabled in mkdocs.yml
Validate mkdocs.yml with `mkdocs build --strict` in CI before publishing

When it happens

Trigger: `cards_layout` (plugin config) or `social.cards_layout` page meta references a layout name that is not one of the built-in layouts and was never registered; a typo in the layout name; or a custom layout plugin providing layouts is missing/disabled.

Common situations: Typo like `cards_layout: default` vs a real name; copying a community layout name without installing its plugin; MkDocs Material version change removing/renaming a layout; YAML indentation placing `cards_layout` at the wrong level so defaults aren't loaded.

Related errors

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