home-assistant/core · error · FailedToLoad

Failed to load blueprint: {err}

Error message

Failed to load blueprint: {err}

What it means

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.

Source

Thrown at homeassistant/components/blueprint/models.py:236

    async def async_reset_cache(self) -> None:
        """Reset the blueprint cache."""
        async with self._load_lock:
            self._blueprints = {}

    def _load_blueprint(self, blueprint_path: str) -> Blueprint:
        """Load a blueprint."""
        try:
            blueprint_data = yaml_util.load_yaml_dict(
                self.blueprint_folder / blueprint_path
            )
        except FileNotFoundError as err:
            raise FailedToLoad(
                self.domain,
                blueprint_path,
                FileNotFoundError(f"Unable to find {blueprint_path}"),
            ) from err
        except HomeAssistantError as err:
            raise FailedToLoad(self.domain, blueprint_path, err) from err

        return Blueprint(
            blueprint_data,
            expected_domain=self.domain,
            path=blueprint_path,
            schema=self._blueprint_schema,
        )

    def _load_blueprints(self) -> dict[str, Blueprint | BlueprintException | None]:
        """Load all the blueprints."""
        blueprint_folder = pathlib.Path(
            self.hass.config.path(BLUEPRINT_FOLDER, self.domain)
        )
        results: dict[str, Blueprint | BlueprintException | None] = {}

        for path in blueprint_folder.glob("**/*.yaml"):
            blueprint_path = str(path.relative_to(blueprint_folder))
            if self._blueprints.get(blueprint_path) is None:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Validate the file is pure YAML mapping: python -c "import yaml; print(type(yaml.safe_load(open('path'))))" should print <class 'dict'>
2. Remove stray markdown/HTML fencing (``` blocks) or front-matter pasted along with the blueprint
3. If the file is not a blueprint at all, move it out of config/blueprints/<domain>/
4. Re-download the raw YAML from the original source

Example fix

# before (file starts with)
```
blueprint:
  name: x
```

# after
blueprint:
  name: x

import yaml

def loadable_blueprint_dict(path: str) -> bool:
    with open(path) as f:
        doc = yaml.safe_load(f)
    return isinstance(doc, dict)

from homeassistant.components.blueprint.errors import FailedToLoad
try:
    bp = await manager.async_get_blueprint(path)
except FailedToLoad as err:
    if not isinstance(err.__cause__, FileNotFoundError):
        # YAML content problem: validate/repair the file

When it happens

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

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

Related errors

• No valid blueprint found in the topic. Blueprint syntax bloc
• No valid blueprint found in the gist. The blueprint file nee
• Invalid blueprint: {msg_or_exc}
• Invalid blueprint: Found incorrect blueprint type {data_doma
• Invalid blueprint: Missing input definition for {', '.join(m

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/4cb6f5652290dafb. Report an issue: GitHub.