home-assistant/core · error · HomeAssistantError

No valid blueprint found in the topic. Blueprint syntax bloc

Error message

No valid blueprint found in the topic. Blueprint syntax blocks need to be marked as YAML or no syntax.

What it means

HomeAssistantError raised by blueprint.importer when fetching a blueprint from a community forum post: none of the post's code blocks parsed as a valid blueprint. The importer iterates code blocks, YAML-parses those marked yaml/no-syntax, checks is_blueprint_config (blueprint name + domain keys), and validates against BLUEPRINT_SCHEMA; if no block passes all stages, blueprint stays None and this error is thrown.

Source

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

        block_content = html.unescape(block_content.strip())

        try:
            data = yaml_util.parse_yaml(block_content)
        except HomeAssistantError:
            if block_syntax == "yaml":
                raise

            continue

        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 topic. Blueprint syntax blocks need to be"
            " marked as YAML or no syntax."
        )

    return ImportedBlueprint(
        f"{post['username']}/{topic['slug']}", block_content, blueprint
    )


async def fetch_blueprint_from_community_post(
    hass: HomeAssistant, url: str
) -> ImportedBlueprint:
    """Get blueprints from a community post url.

    Method can raise aiohttp client exceptions, vol.Invalid.

    Caller needs to implement own timeout.
    """

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Open the forum post and verify there is a code block marked as YAML containing a blueprint: key with name and domain
2. If the block is unmarked or marked text, copy the YAML manually and import it via the UI editor / configuration.yaml instead of by URL
3. Fix the blueprint body so it passes BLUEPRINT_SCHEMA (valid blueprint name, domain, input definitions)
4. Check the linked post is the blueprint topic itself, not a discussion thread referencing it

Example fix

# before (forum post block marked as text)
```text
blueprint:
  domain: automation
...
```
# after
```yaml
blueprint:
  name: Motion light
  domain: automation
  input:
    motion_entity:
      selector: { entity: { domain: binary_sensor } }
```

# Validate a candidate block locally before pointing HA at the post
import yaml
from homeassistant.components.blueprint import importer

data = yaml.safe_load(block_text)
assert importer.is_blueprint_config(data), "block lacks blueprint: name/domain"

def looks_like_blueprint(text: str) -> bool:
    """Cheap pre-check: parses as YAML mapping with a blueprint key."""
    try:
        data = yaml.safe_load(text)
    except yaml.YAMLError:
        return False
    return isinstance(data, dict) and "blueprint" in data and isinstance(data["blueprint"], dict) and "name" in data["blueprint"] and "domain" in data["blueprint"]

try:
    imported = await importer.fetch_blueprint_from_community_post(hass, url)
except HomeAssistantError as err:
    if "No valid blueprint found in the topic" in str(err):
        # fall back to manual import: copy YAML into config/blueprints/<domain>/
        _LOGGER.warning("Falling back to manual blueprint install for %s", url)

When it happens

Trigger: Calling an automation/script that references a blueprint by community URL (or using the blueprint import UI) where the post's blueprint block is marked as a different syntax (e.g. ```text), is not valid YAML, is missing the blueprint: key with name/domain, fails BLUEPRINT_SCHEMA, or the YAML parse errored for every candidate block.

Common situations: Forum post edited so the code block lost its 'yaml' tag; blueprint author wrapped the YAML in ```text or ```jinja; post contains only a discussion snippet, not an importable blueprint; older post format predating the importer's expectations.

Related errors

• No valid blueprint found in the gist. The blueprint file nee
• err
• 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/411682741466ff11. Report an issue: GitHub.