{"record":{"id":"4cb6f5652290dafb","repo":"home-assistant/core","slug":"failed-to-load-blueprint-err","errorCode":null,"errorMessage":"Failed to load blueprint: {err}","messagePattern":"Failed to load blueprint: (.+?)","errorType":"exception","errorClass":"FailedToLoad","httpStatus":null,"severity":"error","filePath":"homeassistant/components/blueprint/models.py","lineNumber":236,"sourceCode":"    async def async_reset_cache(self) -> None:\n        \"\"\"Reset the blueprint cache.\"\"\"\n        async with self._load_lock:\n            self._blueprints = {}\n\n    def _load_blueprint(self, blueprint_path: str) -> Blueprint:\n        \"\"\"Load a blueprint.\"\"\"\n        try:\n            blueprint_data = yaml_util.load_yaml_dict(\n                self.blueprint_folder / blueprint_path\n            )\n        except FileNotFoundError as err:\n            raise FailedToLoad(\n                self.domain,\n                blueprint_path,\n                FileNotFoundError(f\"Unable to find {blueprint_path}\"),\n            ) from err\n        except HomeAssistantError as err:\n            raise FailedToLoad(self.domain, blueprint_path, err) from err\n\n        return Blueprint(\n            blueprint_data,\n            expected_domain=self.domain,\n            path=blueprint_path,\n            schema=self._blueprint_schema,\n        )\n\n    def _load_blueprints(self) -> dict[str, Blueprint | BlueprintException | None]:\n        \"\"\"Load all the blueprints.\"\"\"\n        blueprint_folder = pathlib.Path(\n            self.hass.config.path(BLUEPRINT_FOLDER, self.domain)\n        )\n        results: dict[str, Blueprint | BlueprintException | None] = {}\n\n        for path in blueprint_folder.glob(\"**/*.yaml\"):\n            blueprint_path = str(path.relative_to(blueprint_folder))\n            if self._blueprints.get(blueprint_path) is None:","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/blueprint/models.py#L218-L254","documentation":"FailedToLoad re-raising an arbitrary HomeAssistantError from yaml_util.load_yaml_dict: the file exists but its contents could not be loaded as a YAML dictionary. Typical inner errors are 'expected a single document', duplicate keys, or the file containing a list/scalar instead of a mapping.","triggerScenarios":"A .yaml file in the blueprints folder that is valid YAML but not a dict (e.g. a list), a file with multiple YAML documents, or malformed YAML that raises a HomeAssistantError from the loader; triggered during folder scan or direct async_get_blueprint.","commonSituations":"User pasted a forum page HTML or markdown into a .yaml file; accidentally saved a package file into the blueprints directory; editor wrote a BOM or tabs that break parsing.","solutions":["Validate the file is pure YAML mapping: python -c \"import yaml; print(type(yaml.safe_load(open('path'))))\" should print <class 'dict'>","Remove stray markdown/HTML fencing (``` blocks) or front-matter pasted along with the blueprint","If the file is not a blueprint at all, move it out of config/blueprints/<domain>/","Re-download the raw YAML from the original source"],"exampleFix":"# before (file starts with)\n```\nblueprint:\n  name: x\n```\n\n# after\nblueprint:\n  name: x","handlingStrategy":"validation","validationCode":"import yaml\n\ndef loadable_blueprint_dict(path: str) -> bool:\n    with open(path) as f:\n        doc = yaml.safe_load(f)\n    return isinstance(doc, dict)","typeGuard":null,"tryCatchPattern":"from homeassistant.components.blueprint.errors import FailedToLoad\ntry:\n    bp = await manager.async_get_blueprint(path)\nexcept FailedToLoad as err:\n    if not isinstance(err.__cause__, FileNotFoundError):\n        # YAML content problem: validate/repair the file","preventionTips":["Save blueprints as raw YAML only — no markdown fences or commentary around them","Lint changed files with a YAML validator before HA rescans the folder"],"tags":["blueprint","yaml","parse-error"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}