{"record":{"id":"60503633fb65abed","repo":"squidfunk/mkdocs-material","slug":"expected-iterable-tags-but-received-value","errorCode":null,"errorMessage":"Expected iterable tags, but received: {value}","messagePattern":"Expected iterable tags, but received: (.+?)","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"src/plugins/tags/structure/tag/options.py","lineNumber":82,"sourceCode":"        Validate list of tags.\n\n        If the value is `None`, an empty set is returned. Otherwise, the value\n        is expected to be a list of tags, which is converted to a set of tags.\n        This means that tags are automatically deduplicated. Note that tags are\n        not expanded here, as the set is intended to be checked exactly.\n\n        Arguments:\n            value: The value to validate.\n\n        Returns:\n            A set of tags.\n        \"\"\"\n        if value is None:\n            return set()\n\n        # Ensure tags are iterable\n        if not isinstance(value, Iterable) or isinstance(value, str):\n            raise ValidationError(\n                f\"Expected iterable tags, but received: {value}\"\n            )\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)","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/tags/structure/tag/options.py#L64-L100","documentation":"TagSet.run_validation validates tag values coming from page front matter (the 'tags' key) or from plugin filters like tags listings. The value must be an iterable collection of tags — but explicitly NOT a plain string, since a string would iterate character-by-character. This mkdocs ValidationError is raised when the value is neither None nor a non-string iterable (e.g. a number, a bool, or a single string).","triggerScenarios":"A page's front matter sets tags: my-tag (a bare string instead of a list); tags: true or tags: 3; or a TagSet filter option receives a scalar instead of a list of tags.","commonSituations":"YAML front matter typo where the author forgot the list syntax and wrote tags: foo instead of tags: [foo] or tags:\\n  - foo; copying a single-tag example from docs; a template or script injecting a scalar into front matter.","solutions":["Wrap the value in a list in front matter: tags: [my-tag] or tags:\\n  - my-tag","Check YAML indentation — an incorrectly indented block can parse as a scalar string instead of a list","If the page has no tags, omit the key or use tags: [] (null is allowed and yields an empty set)","Validate front matter with mkdocs serve/build and inspect the offending page named in the error context"],"exampleFix":"# before (front matter)\n---\ntags: my-tag\n---\n# after\n---\ntags:\n  - my-tag\n---","handlingStrategy":"validation","validationCode":"import yaml\ndef validate_tags(fm: dict) -> None:\n    tags = fm.get(\"tags\")\n    if tags is None:\n        return\n    if isinstance(tags, str) or not hasattr(tags, \"__iter__\"):\n        raise ValueError(f\"tags must be a list, got: {tags!r}\")\nvalidate_tags(yaml.safe_load(front_matter))","typeGuard":"def is_tag_list(value: object) -> bool:\n    return value is None or (\n        isinstance(value, (list, tuple, set))\n        and not isinstance(value, str)\n    )","tryCatchPattern":"from mkdocs.config.base import ValidationError\ntry:\n    page_tags = tag_option.run_validation(raw_value)\nexcept ValidationError as err:\n    log.error(\"Bad 'tags' front matter on page: %s\", err)","preventionTips":["Always write front matter tags as a YAML list, never a bare string","Use tags: [single-tag] bracket syntax to avoid indentation mistakes","Omit the tags key entirely for untagged pages","Lint front matter YAML in CI before building","Remember strings iterate per-character, which is why the plugin rejects them"],"tags":["yaml","mkdocs","front-matter","validation"],"backgroundTag":"invalid-front-matter-type","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}