squidfunk/mkdocs-material · error · ConfigurationError

Error reading filter configuration in '{key}': {e}

Error message

Error reading filter configuration in '{key}':
{e}

What it means

The preview extension's get_filter() builds a FileFilter from user configuration. After validating the filter configuration, any errors (not warnings) cause it to raise a MkDocs ConfigurationError naming the config key and the underlying validation error. It is thrown because the filter spec (e.g. path patterns) is malformed and cannot be turned into a usable filter.

Source

Thrown at src/extensions/preview.py:198

    Arguments:
        settings: The settings.
        key: The key in the settings.

    Returns:
        The file filter.
    """
    config = FilterConfig()
    config.load_dict(settings.get(key) or {})

    # Validate filter configuration
    errors, warnings = config.validate()
    for _, w in warnings:
        log.warning(
            f"Error reading filter configuration in '{key}':\n"
            f"{w}"
        )
    for _, e in errors:
        raise ConfigurationError(
            f"Error reading filter configuration in '{key}':\n"
            f"{e}"
        )

    # Return file filter
    return FileFilter(config = config) # type: ignore

def makeExtension(**kwargs):
    """
    Register Markdown extension.

    Arguments:
        **kwargs: Configuration options.

    Returns:
        The Markdown extension.
    """
    return PreviewExtension(**kwargs)

View on GitHub (pinned to e2136532f4)

Solutions

1. Read the error detail after the newline — it names the exact invalid option/value.
2. Fix the filter configuration under that key in mkdocs.yml to match the documented schema (correct types, valid patterns).
3. Validate with mkdocs serve locally so config errors surface before builds/CI.
4. Address warnings too, as they often indicate values that will become errors later.

Example fix

# before (mkdocs.yml)
markdown_extensions:
  - preview:
      configurations:
        - sources: true

# after
markdown_extensions:
  - preview:
      configurations:
        - sources:
            icon_prefix: "material/"

# Validate preview filter config before building
import yaml
cfg = yaml.safe_load(open("mkdocs.yml"))
for c in cfg["markdown_extensions"][1]["preview"]["configurations"]:
    assert "sources" in c or "targets" in c, "preview configuration needs sources/targets"

def filter_config_is_valid(cfg: dict) -> bool:
    return isinstance(cfg, dict) and (
        "sources" in cfg or "targets" in cfg
    ) and isinstance(cfg.get("sources"), (list, dict, type(None)))

try:
    mkdocs.commands.build.build(cfg)
except ConfigurationError as e:
    if str(e).startswith("Error reading filter configuration"):
        print("Fix the preview filter options in mkdocs.yml:", e)
    else:
        raise

When it happens

Trigger: Calling get_filter() (via run) with an invalid entry under the extension's configured filter key — e.g. wrong-typed path patterns or unsupported options in the preview extension's filter configuration in mkdocs.yml.

Common situations: YAML typos in mkdocs.yml (wrong indentation, string vs list), using glob patterns the filter doesn't accept, copying an example config from a different extension or version.

Related errors

• Couldn't find author '{id}'
• Couldn't find '{separator}' in post '{path}' in '{docs}'
• Aborted with {len(errors)} configuration errors
• Expected string, but received: {url}
• Expected string, but received: {title}

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