squidfunk/mkdocs-material · error · PluginError

Error reading listing configuration in '{path}': {e}

Error message

Error reading listing configuration in '{path}':
{e}

What it means

`_resolve` loads a listing configuration from a YAML file and validates it; parse/validation failures (and warnings) are collected, and the first error is re-raised as this PluginError with the file's relative path and the underlying error message, aborting resolution.

Source

Thrown at src/plugins/tags/structure/listing/manager/__init__.py:374

                    f"configurations: {keys}"
                )

        # Otherwise, handle inline listing configuration
        else:
            config = ListingConfig(config_file_path = path)
            config.load_dict(data or {})

            # Validate listing configuration
            errors, warnings = config.validate()
            for _, w in warnings:
                path = os.path.relpath(path)
                log.warning(
                    f"Error reading listing configuration in '{path}':\n"
                    f"{w}"
                )
            for _, e in errors:
                path = os.path.relpath(path)
                raise PluginError(
                    f"Error reading listing configuration in '{path}':\n"
                    f"{e}"
                )

        # Inherit shadow tags configuration, unless explicitly set
        if not isinstance(config.shadow, bool):
            config.shadow = self.config.shadow

        # Inherit layout configuration, unless explicitly set
        if not isinstance(config.layout, str):
            config.layout = self.config.listings_layout

        # Inherit table of contents configuration, unless explicitly set
        if not isinstance(config.toc, bool):
            config.toc = self.config.listings_toc

        # Return listing configuration
        return config

View on GitHub (pinned to e2136532f4)

Solutions

1. Open the YAML file named in the error and fix the specific problem listed after the newline (syntax or validation error).
2. Validate the file with `yaml.safe_load(open(path))` and compare its keys against the tags plugin listing schema (`listing`, `scope`, `tags`, etc.).
3. Correct the file path in the plugin's `listings` config if loading failed.
4. Bump/align mkdocs-material version if the schema key was renamed in your installed release.

Example fix

# before listings.yml
taggings:
  scope: ...

# after
listing:
  scope: ...

import yaml
for path in listing_paths:
    with open(path) as f:
        doc = yaml.safe_load(f)
    assert isinstance(doc, dict), f"{path}: listing config must be a mapping"
    assert set(doc) <= {'listing', 'scope', 'tags', ...}, f"{path}: unknown keys {set(doc)}"

def is_valid_listing_doc(doc):
    return isinstance(doc, dict) and isinstance(doc.get('listing', {}), dict)

from mkdocs.exceptions import PluginError
try:
    manager.replace(...)
except PluginError as e:
    log.error(f"Listing YAML problem: {e}")
    raise SystemExit(1)

When it happens

Trigger: A listing YAML file referenced from the tags plugin config contains invalid YAML or fails schema validation (e.g. non-dictionary root, unknown/invalid keys like a malformed `scope` or `tags` value); the path is wrong so loading itself fails.

Common situations: Sharing listing configs across projects with tabs-vs-spaces YAML errors; editing the YAML and introducing a bad key; referencing an external listings file that moved; schema changes between mkdocs-material versions.

Related errors

• Error reading tags of page '{path}' in '{docs}': {e}
• Couldn't find listing configuration: {data}. Available confi
• Couldn't find layout '{name}'
• Expected dictionary, but received: {data}
• Expected list, but received: {mappings}

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