home-assistant/core · error · HomeAssistantError

No valid blueprint found in the gist. The blueprint file nee

Error message

No valid blueprint found in the gist. The blueprint file needs to end with '.yaml'

What it means

HomeAssistantError raised by blueprint.importer when fetching from a GitHub gist: none of the gist files qualified as a valid blueprint. The importer only considers files ending in .yaml, parses them, requires is_blueprint_config to pass (blueprint key with name and domain), and validates against BLUEPRINT_SCHEMA; if no file clears every check this error names the .yaml-extension requirement.

Source

Thrown at homeassistant/components/blueprint/importer.py:216

    filename: str | None = None
    content: str

    for filename, info in gist["files"].items():
        if not filename.endswith(".yaml"):
            continue

        content = info["content"]
        data = yaml_util.parse_yaml(content)

        if not is_blueprint_config(data):
            continue
        assert isinstance(data, dict)

        blueprint = Blueprint(data, schema=BLUEPRINT_SCHEMA)
        break

    if blueprint is None:
        raise HomeAssistantError(
            "No valid blueprint found in the gist. The blueprint file needs to end with"
            " '.yaml'"
        )
    if TYPE_CHECKING:
        assert isinstance(filename, str)

    return ImportedBlueprint(
        f"{gist['owner']['login']}/{filename[:-5]}", content, blueprint
    )


async def fetch_blueprint_from_website_url(
    hass: HomeAssistant, url: str
) -> ImportedBlueprint:
    """Get a blueprint from our website."""
    if (WEBSITE_PATTERN.match(url)) is None:
        raise UnsupportedUrl("Not a Home Assistant website URL")

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Rename the gist file so it ends exactly with .yaml
2. Ensure the file starts with a blueprint: block containing name and domain (plus input)
3. Validate the YAML locally (yamllint / HA check_config) and fix schema errors
4. Alternatively copy the blueprint into config/blueprints/automations/<name>.yaml manually

Example fix

# before: gist file blueprint.yml missing header
mode: single
trigger: []
# after: file renamed to blueprint.yaml with valid header
blueprint:
  name: Motion light
  domain: automation
  input:
    motion_entity:
      selector: { entity: { domain: binary_sensor } }
mode: single
trigger: []

# Verify gist files locally before importing
import yaml, requests

gist = requests.get(gist_api_url, timeout=10).json()
for fname, fdata in gist["files"].items():
    if fname.endswith(".yaml"):
        parsed = yaml.safe_load(fdata["content"])
        assert isinstance(parsed, dict) and "blueprint" in parsed, f"{fname} not a blueprint"
        break

def gist_has_blueprint_file(gist: dict) -> bool:
    """True if at least one .yaml file is a blueprint config."""
    for f in gist.get("files", {}).values():
        if f["filename"].endswith(".yaml"):
            try:
                data = yaml.safe_load(f["content"])
            except yaml.YAMLError:
                continue
            if (isinstance(data, dict)
                    and isinstance(data.get("blueprint"), dict)
                    and {"name", "domain"} <= data["blueprint"].keys()):
                return True
    return False

try:
    imported = await importer.fetch_blueprint_from_gist(hass, gist_url)
except HomeAssistantError as err:
    if "No valid blueprint found in the gist" in str(err):
        _LOGGER.warning("Gist rejected; ensure the file is .yaml with a blueprint header")

When it happens

Trigger: Importing a gist URL where the blueprint is stored as .yml or .txt, the YAML has no blueprint: key, the schema validation fails (missing name/domain under blueprint), or the YAML doesn't parse. Every candidate file is skipped and blueprint remains None.

Common situations: Gist file named blueprint.yml instead of blueprint.yaml; blueprint body pasted without the blueprint header (name/domain/input); gist contains only a README or non-blueprint YAML; schema-breaking typo in the blueprint section.

Related errors

• No valid blueprint found in the topic. Blueprint syntax bloc
• Invalid blueprint: {msg_or_exc}
• Invalid blueprint: Found incorrect blueprint type {data_doma
• Invalid blueprint: Missing input definition for {', '.join(m
• Failed to load blueprint: {err}

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