home-assistant/core · error · FailedToLoad

Failed to load blueprint: Unable to find {blueprint_path}

Error message

Failed to load blueprint: Unable to find {blueprint_path}

What it means

FailedToLoad wrapping FileNotFoundError: _load_blueprint could not find the blueprint file under the domain's blueprint folder. The path given in use_blueprint.path is resolved relative to config/blueprints/<domain>/, so a wrong path, missing file, or wrong extension produces this.

Source

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

    @property
    def blueprint_folder(self) -> pathlib.Path:
        """Return the blueprint folder."""
        return pathlib.Path(self.hass.config.path(BLUEPRINT_FOLDER, self.domain))

    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)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check the exact path in the error: it is relative to config/blueprints/<automation|script>/ — create or restore the file there
2. Re-import the blueprint from its source URL, which writes the file and picks the correct folder
3. Fix the use_blueprint.path string in the consuming automation to match the real filename and subfolder

Example fix

# before
use_blueprint:
  path: motion_lights.yaml

# after (file lives in blueprints/automation/domotics/motion_lights.yaml)
use_blueprint:
  path: domotics/motion_lights.yaml

from pathlib import Path

def blueprint_file_exists(hass, domain: str, path: str) -> bool:
    return (Path(hass.config.path("blueprints", domain)) / path).is_file()

from homeassistant.components.blueprint.errors import FailedToLoad
try:
    bp = await manager.async_get_blueprint(path)
except FailedToLoad as err:
    if isinstance(err.__cause__, FileNotFoundError):
        # offer to re-import the blueprint or fix the path

When it happens

Trigger: An automation/script references use_blueprint.path: my_bp.yaml but config/blueprints/automation/my_bp.yaml does not exist; path includes a subdirectory that is missing; file saved with .yml versus .yaml mismatch; calling async_get_blueprint directly with an unknown path.

Common situations: Blueprint file deleted or renamed; blueprint never actually imported (import dialog closed early); path typo; blueprint stored in the wrong domain folder.

Related errors

• System generated users cannot disable multi-factor auth modu
• wrong_file_path
• err
• No valid blueprint found in the topic. Blueprint syntax bloc
• No valid blueprint found in the gist. The blueprint file nee

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