{"record":{"id":"1741b63b810801a1","repo":"squidfunk/mkdocs-material","slug":"expected-a-str-int-float-or-bool-but-rec","errorCode":null,"errorMessage":"Expected a {str}, {int}, {float} or {bool} but received: {type(tag)} at index {index}","messagePattern":"Expected a (.+?), (.+?), (.+?) or (.+?) but received: (.+?) at index (.+?)","errorType":"validation","errorClass":"ValidationError","httpStatus":null,"severity":"error","filePath":"src/plugins/tags/structure/tag/options.py","lineNumber":90,"sourceCode":"            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)\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","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/tags/structure/tag/options.py#L72-L108","documentation":"TagSet.run_validation iterates the tags value and requires each element to be a str, int, float, or bool, which is then coerced to a Tag string. This ValidationError is raised with the offending Python type and index when an element is another type (dict, list, None, datetime, etc.), because tags must be simple scalar values nameable as strings.","triggerScenarios":"A front matter tags list contains nested structures — e.g. tags:\\n  - name: foo (a dict), tags: [foo, [bar]] (nested list), tags: [foo, null] — or a filter option passes objects instead of scalar tag names.","commonSituations":"YAML anchors/merge keys producing dicts inside the tags list; authors putting key-value metadata under tags; a front matter serializer emitting dates or None values into the list.","solutions":["Make every element of the tags list a scalar string: tags: [foo, bar]","Replace nested mappings like - name: foo with the plain tag name - foo","Remove null/empty entries from the list","Quote tags that YAML would otherwise parse as other types (e.g. \"2024-01-01\" to keep it a string, though date-like strings already parse as strings only if quoted)","Run the page through a YAML linter to spot unintended nesting"],"exampleFix":"# before (front matter)\n---\ntags:\n  - name: python\n    category: lang\n---\n# after\n---\ntags:\n  - python\n---","handlingStrategy":"type-guard","validationCode":"import yaml\ndef validate_tag_items(fm: dict) -> None:\n    for i, tag in enumerate(fm.get(\"tags\") or []):\n        if not isinstance(tag, (str, int, float, bool)):\n            raise ValueError(f\"tags[{i}] must be scalar, got {type(tag).__name__}\")\nvalidate_tag_items(yaml.safe_load(front_matter))","typeGuard":"def is_scalar_tag(tag: object) -> bool:\n    return isinstance(tag, (str, int, float, bool))","tryCatchPattern":"from mkdocs.config.base import ValidationError\ntry:\n    page_tags = tag_option.run_validation(raw_value)\nexcept ValidationError as err:\n    log.error(\"Non-scalar tag in front matter: %s\", err)","preventionTips":["Keep tags list flat: one plain name per item, no nested mappings","Quote date-like or numeric tags to control their parsed type","Avoid YAML anchors/merge keys inside the tags list","Check with a YAML linter that tags parses as list[str]","Strip null entries from generated front matter"],"tags":["yaml","mkdocs","front-matter","type-error"],"backgroundTag":"invalid-front-matter-type","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}