{"record":{"id":"e7e9e495bbf868c8","repo":"squidfunk/mkdocs-material","slug":"error-reading-filter-configuration-in-key-e","errorCode":null,"errorMessage":"Error reading filter configuration in '{key}':\n{e}","messagePattern":"Error reading filter configuration in '(.+?)':\n(.+?)","errorType":"exception","errorClass":"ConfigurationError","httpStatus":null,"severity":"error","filePath":"src/extensions/preview.py","lineNumber":198,"sourceCode":"    Arguments:\n        settings: The settings.\n        key: The key in the settings.\n\n    Returns:\n        The file filter.\n    \"\"\"\n    config = FilterConfig()\n    config.load_dict(settings.get(key) or {})\n\n    # Validate filter configuration\n    errors, warnings = config.validate()\n    for _, w in warnings:\n        log.warning(\n            f\"Error reading filter configuration in '{key}':\\n\"\n            f\"{w}\"\n        )\n    for _, e in errors:\n        raise ConfigurationError(\n            f\"Error reading filter configuration in '{key}':\\n\"\n            f\"{e}\"\n        )\n\n    # Return file filter\n    return FileFilter(config = config) # type: ignore\n\ndef makeExtension(**kwargs):\n    \"\"\"\n    Register Markdown extension.\n\n    Arguments:\n        **kwargs: Configuration options.\n\n    Returns:\n        The Markdown extension.\n    \"\"\"\n    return PreviewExtension(**kwargs)","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/extensions/preview.py#L180-L216","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the error detail after the newline — it names the exact invalid option/value.","Fix the filter configuration under that key in mkdocs.yml to match the documented schema (correct types, valid patterns).","Validate with mkdocs serve locally so config errors surface before builds/CI.","Address warnings too, as they often indicate values that will become errors later."],"exampleFix":"# before (mkdocs.yml)\nmarkdown_extensions:\n  - preview:\n      configurations:\n        - sources: true\n\n# after\nmarkdown_extensions:\n  - preview:\n      configurations:\n        - sources:\n            icon_prefix: \"material/\"","handlingStrategy":"validation","validationCode":"# Validate preview filter config before building\nimport yaml\ncfg = yaml.safe_load(open(\"mkdocs.yml\"))\nfor c in cfg[\"markdown_extensions\"][1][\"preview\"][\"configurations\"]:\n    assert \"sources\" in c or \"targets\" in c, \"preview configuration needs sources/targets\"","typeGuard":"def filter_config_is_valid(cfg: dict) -> bool:\n    return isinstance(cfg, dict) and (\n        \"sources\" in cfg or \"targets\" in cfg\n    ) and isinstance(cfg.get(\"sources\"), (list, dict, type(None)))","tryCatchPattern":"try:\n    mkdocs.commands.build.build(cfg)\nexcept ConfigurationError as e:\n    if str(e).startswith(\"Error reading filter configuration\"):\n        print(\"Fix the preview filter options in mkdocs.yml:\", e)\n    else:\n        raise","preventionTips":["Run mkdocs serve locally and fix all config warnings before committing.","Copy filter option syntax only from the docs of your installed version.","Keep mkdocs.yml under YAML lint / schema validation in CI.","Prefer explicit, fully-spelled option keys over abbreviated examples."],"tags":["python","mkdocs","configuration","validation"],"backgroundTag":"invalid-config-option","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}