{"record":{"id":"7ee4dd0abe38573d","repo":"squidfunk/mkdocs-material","slug":"tags-not-in-allow-list-join-tag-name-for-ta","errorCode":null,"errorMessage":"Tags not in allow list: {','.join([tag.name for tag in invalid])}","messagePattern":"Tags not in allow list: (.+?)","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"src/plugins/tags/structure/tag/options.py","lineNumber":102,"sourceCode":"            )\n\n        # Ensure tags are valid\n        tags: set[Tag] = set()\n        for index, tag in enumerate(value):\n            if not isinstance(tag, (str, int, float, bool)):\n                raise ValidationError(\n                    f\"Expected a {str}, {int}, {float} or {bool} \"\n                    f\"but received: {type(tag)} at index {index}\"\n                )\n\n            # Coerce tag to string and add to set\n            tags.add(Tag(str(tag)))\n\n        # Ensure tags are in allow list, if any\n        if self.allowed:\n            invalid = tags.difference(self.allowed)\n            if invalid:\n                raise ValidationError(\n                    \"Tags not in allow list: \" +\n                    \",\".join([tag.name for tag in invalid])\n                )\n\n        # Return set of tags\n        return tags\n","sourceCodeStart":84,"sourceCodeEnd":109,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/tags/structure/tag/options.py#L84-L109","documentation":"When the tags plugin configuration defines an allowed tag set (e.g. via tags_allowed or a listing's allowed tags), TagSet.run_validation rejects any tag not in that allow list. The error lists all offending tag names joined by commas, enforcing a controlled vocabulary across the project.","triggerScenarios":"A page's front matter (or a listing filter) uses a tag such as 'python' while the configured allowed set (built from config like allowed_tags or the tags defined in a central listing) only contains other tags — tags.difference(self.allowed) is non-empty.","commonSituations":"Typos in tag names (pyhton vs python); a new tag used on a page before being registered in the allowed list config; case mismatches (Python vs python); tags added in a shared mapping from another project that aren't declared locally.","solutions":["Add the missing tags to the allowed list in mkdocs.yml (the tags plugin/listing configuration defining allowed tags)","Fix the typo in the page's front matter to match an allowed tag exactly (case-sensitive)","Check the error's comma-separated list and correct every listed tag","If the tag comes from a shared mapping file, ensure it is also declared in this project's allowed set","Consider running a script that diffs front matter tags against the configured allow list in CI"],"exampleFix":"# mkdocs.yml before\ntags:\n  allowed_tags: [python, mkdocs]\n# page uses: tags: [pyhton]\n# after (fix the typo)\ntags: [python]","handlingStrategy":"validation","validationCode":"import re, yaml\nALLOWED = {\"python\", \"mkdocs\"}  # mirror of mkdocs.yml allowed_tags\nused = set()\nfor page in PAGES:\n    fm = yaml.safe_load(page.front_matter)\n    used |= {str(t) for t in (fm.get(\"tags\") or [])}\ninvalid = used - ALLOWED\nif invalid:\n    raise ValueError(f\"Tags not in allow list: {','.join(sorted(invalid))}\")","typeGuard":"def tags_in_allow_list(tags: list[str], allowed: set[str]) -> bool:\n    return all(str(t) in allowed for t in tags)","tryCatchPattern":"from mkdocs.config.base import ValidationError\ntry:\n    page_tags = tag_option.run_validation(raw_value)\nexcept ValidationError as err:\n    log.error(\"Tag allow-list violation: %s\", err)\n    # parse names after 'Tags not in allow list: ' to report/fix them","preventionTips":["Maintain a single source of truth for allowed tags in mkdocs.yml and share it","Check tag spelling and case exactly against the allow list (it is case-sensitive)","Add new tags to the allow list before first use in front matter","Run a CI check diffing front matter tags against the configured allow list","When consuming shared mappings from other projects, merge their tags into the local allow list"],"tags":["mkdocs","configuration","validation","allow-list"],"backgroundTag":"tag-not-in-allow-list","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}