{"record":{"id":"584b930db21a2f25","repo":"squidfunk/mkdocs-material","slug":"couldn-t-find-layout-name","errorCode":null,"errorMessage":"Couldn't find layout '{name}'","messagePattern":"Couldn't find layout '(.+?)'","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/social/plugin.py","lineNumber":800,"sourceCode":"                self.card_layouts[name] = layout\n                self.card_variables[name] = []\n\n                # Extract variables for each layer from layout\n                for layer in layout.layers:\n                    variables = _extract(layer, self.card_env, config)\n                    self.card_variables[name].append(variables)\n\n                    # Set default values for for layer size, if not given\n                    for key, value in layer.size.items():\n                        if value == 0:\n                            layer.size[key] = layout.size[key]\n\n            # Abort, since we're done\n            break\n\n        # Abort if the layout could not be resolved\n        if name not in self.card_layouts:\n            raise PluginError(f\"Couldn't find layout '{name}'\")\n\n        # Return layout and variables\n        return self.card_layouts[name], self.card_variables[name]\n\n    # Resolve icon with given name - this function searches for the icon in all\n    # known theme directories, including custom directories specified by the\n    # author, which allows for using custom icons in cards. If the icon cannot\n    # be resolved, the plugin must abort with an error.\n    def _resolve_icon(self, name: str, config: MkDocsConfig):\n        for base in config.theme.dirs:\n            path = os.path.join(base, \".icons\", f\"{name}.svg\")\n            path = os.path.normpath(path)\n\n            # Skip if icon does not exist and try next directory\n            if not os.path.isfile(path):\n                continue\n\n            # Open and return icon","sourceCodeStart":782,"sourceCodeEnd":818,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/social/plugin.py#L782-L818","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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."],"exampleFix":"# before\nplugins:\n  - social:\n      cards_layout: custum-big\n\n# after\nplugins:\n  - social:\n      cards_layout: custom:big  # or a valid built-in name like 'default'","handlingStrategy":"validation","validationCode":"import mkdocs_social  # social plugin internals\n# before building:\nplugin = config.plugins['social']\nif cards_layout_name not in plugin.card_layouts:\n    raise SystemExit(f\"Unknown cards_layout '{cards_layout_name}'. Known: {sorted(plugin.card_layouts)}\")","typeGuard":null,"tryCatchPattern":"from mkdocs.exceptions import PluginError\ntry:\n    layout, variables = plugin._resolve_layout(name)\nexcept PluginError as e:\n    log.error(f\"Bad cards_layout: {e}\")\n    layout, variables = plugin._resolve_layout('default')  # or abort","preventionTips":["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"],"tags":["mkdocs-material","social-plugin","configuration","social-cards"],"backgroundTag":"unknown-layout-name","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}