squidfunk/mkdocs-material · error · PluginError

Couldn't find listing configuration: {data}. Available confi

Error message

Couldn't find listing configuration: {data}. Available configurations: {keys}

What it means

When resolving a listing in the tags plugin, a string `data` value is treated as a reference into `config.listings_map` (listings defined under `plugins.tags.listings` in mkdocs.yml). If the key is missing, `_resolve` raises this PluginError listing all available configuration keys so the developer can correct the reference.

Source

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

        """
        Resolve listing configuration.

        Arguments:
            page: The page the listing in embedded in.
            args: The arguments, as parsed from Markdown.

        Returns:
            The listing configuration.
        """
        data = yaml.safe_load(args)
        path = page.file.abs_src_path

        # Try to resolve available listing configuration
        if isinstance(data, str):
            config = self.config.listings_map.get(data, None)
            if not config:
                keys = ", ".join(self.config.listings_map.keys())
                raise PluginError(
                    f"Couldn't find listing configuration: {data}. Available "
                    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:

View on GitHub (pinned to e2136532f4)

Solutions

Define the referenced listing under `plugins.tags.listings` in mkdocs.yml, or fix the name to match an existing key (the error lists valid keys).
Check YAML indentation so each listing sits directly under `listings:` with a unique key.
Update pages' `data:` references after renaming a listing.
Use inline listing configuration (`data` as a mapping) instead of a named reference for one-off listings.

Example fix

# before (mkdocs.yml)
- tags:
    listings: []
# page: data: posts

# after
- tags:
    listings:
      posts:
        scope: ...

Defensive patterns

Strategy: validation

Validate before calling

# ensure every data: reference in pages has a matching listings key
refs = collect_listing_refs_from_pages(docs_dir)
defined = set((config.plugins['tags'].config.listings or {}).keys())
missing = refs - defined
assert not missing, f"Undefined listings referenced in pages: {missing}. Defined: {sorted(defined)}"

Try / catch

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

Prevention

Define every named listing under plugins.tags.listings before referencing it
Grep pages for `data:` listing references and cross-check keys after renames
Validate YAML indentation so listings land inside the listings map

When it happens

Trigger: A page embeds a listing with `data: <name>` whose name has no matching entry in the `listings` plugin option; the listings YAML is indented wrong so the map is empty; the referenced listing was renamed or removed.

Common situations: Typo in the listing name; forgetting to define `listings:` in the tags plugin config before referencing it from pages; multi-document refactors renaming listings; copying examples that assume custom listing names.

Related errors

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