squidfunk/mkdocs-material · error · PluginError

Error reading layout file '{path}' in '{base}': {e}

Error message

Error reading layout file '{path}' in '{base}':
{e}

What it means

Social card layouts can be customized via YAML layout files. When _resolve_layout attempts to load such a file and the YAML cannot be parsed (any exception during open/parse/load_dict), the plugin wraps the original exception message into a PluginError showing the relative path and base directory, so syntax mistakes in the custom layout are surfaced clearly to the author.

Source

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

        ]:
            path = os.path.join(base, f"{name}.yml")
            path = os.path.normpath(path)

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

            # Open file and parse as YAML
            with open(path, encoding = "utf-8-sig") as f:
                layout: Layout = Layout(config_file_path = path)
                try:
                    layout.load_dict(yaml.load(f, SafeLoader) or {})

                # The layout could not be loaded because of a syntax error,
                # which we display to the author with a nice error message
                except Exception as e:
                    path = os.path.relpath(path, base)
                    raise PluginError(
                        f"Error reading layout file '{path}' in '{base}':\n"
                        f"{e}"
                    )

                # Validate layout and abort if errors occurred
                errors, warnings = layout.validate()
                for _, w in warnings:
                    log.warning(w)
                for _, e in errors:
                    path = os.path.relpath(path, base)
                    raise PluginError(
                        f"Error reading layout file '{path}' in '{base}':\n"
                        f"{e}"
                    )

                # Store layout and variables
                self.card_layouts[name] = layout
                self.card_variables[name] = []

View on GitHub (pinned to e2136532f4)

Solutions

1. Look at the '{e}' message in the error for the exact YAML problem and fix the syntax (indentation, tabs, quoting) at that line
2. Validate the file with a YAML parser: python -c 'import yaml;print(yaml.safe_load(open("layout.yml")))'
3. Compare against a working upstream layout file and adjust keys/types to match the expected schema

Example fix

# before (tabs break YAML)
options:
	background_color: '#000'
# after
options:
  background_color: '#000000'

import yaml, sys
try:
    data = yaml.safe_load(open("custom-layout.yml"))
except yaml.YAMLError as e:
    sys.exit(f"Invalid layout YAML: {e}")

try:
    mkdocs build
except SystemExit:
    # message contains the YAML exception; fix the indicated line
    pass

When it happens

Trigger: on_page_markdown, on_post_page or _generate resolves a card layout defined in a .yml file whose content raises during yaml.load(..., SafeLoader) or layout.load_dict — e.g. bad indentation, tabs, wrong types, or unparseable YAML.

Common situations: Copy-pasting a custom layout with wrong indentation or tabs; using YAML features unsafe for SafeLoader; invalid data types for layout options (string where size/int expected); an empty or truncated layout file.

Related errors

• Error reading metadata of post '{path}' in '{docs}': {e}
• Error reading meta file '{path}' in '{docs}': {e}
• Error reading authors file '{path}' in '{docs}': {e}
• Error reading metadata of post '{path}' in '{docs}': Expecte
• Couldn't parse due to possible syntax error in HTML: {frag

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