What causes "Tags not in allow list: {','.join([tag.name for tag in invalid])}" in squidfunk/mkdocs-material?

Add the missing tags to the allowed list in mkdocs.yml (the tags plugin/listing configuration defining allowed tags)

squidfunk/mkdocs-material · error · ValidationError

Tags not in allow list: {','.join([tag.name for tag in inval

Error message

Tags not in allow list: {','.join([tag.name for tag in invalid])}

What it means

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.

Source

Thrown at src/plugins/tags/structure/tag/options.py:102

            )

        # Ensure tags are valid
        tags: set[Tag] = set()
        for index, tag in enumerate(value):
            if not isinstance(tag, (str, int, float, bool)):
                raise ValidationError(
                    f"Expected a {str}, {int}, {float} or {bool} "
                    f"but received: {type(tag)} at index {index}"
                )

            # Coerce tag to string and add to set
            tags.add(Tag(str(tag)))

        # Ensure tags are in allow list, if any
        if self.allowed:
            invalid = tags.difference(self.allowed)
            if invalid:
                raise ValidationError(
                    "Tags not in allow list: " +
                    ",".join([tag.name for tag in invalid])
                )

        # Return set of tags
        return tags

View on GitHub (pinned to e2136532f4)

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

Example fix

# mkdocs.yml before
tags:
  allowed_tags: [python, mkdocs]
# page uses: tags: [pyhton]
# after (fix the typo)
tags: [python]

Defensive patterns

Strategy: validation

Validate before calling

import re, yaml
ALLOWED = {"python", "mkdocs"}  # mirror of mkdocs.yml allowed_tags
used = set()
for page in PAGES:
    fm = yaml.safe_load(page.front_matter)
    used |= {str(t) for t in (fm.get("tags") or [])}
invalid = used - ALLOWED
if invalid:
    raise ValueError(f"Tags not in allow list: {','.join(sorted(invalid))}")

Type guard

def tags_in_allow_list(tags: list[str], allowed: set[str]) -> bool:
    return all(str(t) in allowed for t in tags)

Try / catch

from mkdocs.config.base import ValidationError
try:
    page_tags = tag_option.run_validation(raw_value)
except ValidationError as err:
    log.error("Tag allow-list violation: %s", err)
    # parse names after 'Tags not in allow list: ' to report/fix them

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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