home-assistant/core · error · HomeAssistantError

err

Error message

err

What it means

This error is produced when an automation's blueprint inputs cannot be substituted into the blueprint's configuration; async_substitute() raises UndefinedSubstitution because a required input is missing or references an undefined placeholder. Depending on flags, it is logged (warn_on_errors), re-raised as HomeAssistantError (raise_on_errors), or converted into a minimal failed config with ValidationStatus.FAILED_BLUEPRINT so the automation is not loaded. It originates from Home Assistant's blueprint machinery in homeassistant/helpers/blueprint.py.

Source

Thrown at homeassistant/components/automation/config.py:195

            if raise_on_errors:
                raise
            return _minimal_config(ValidationStatus.FAILED_BLUEPRINT, err, config)

        raw_blueprint_inputs = blueprint_inputs.config_with_inputs

        try:
            config = blueprint_inputs.async_substitute()
            raw_config = dict(config)
        except UndefinedSubstitution as err:
            if warn_on_errors:
                LOGGER.error(
                    "Blueprint '%s' failed to generate automation with inputs %s: %s",
                    blueprint_inputs.blueprint.name,
                    blueprint_inputs.inputs,
                    err,
                )
            if raise_on_errors:
                raise HomeAssistantError(err) from err
            return _minimal_config(ValidationStatus.FAILED_BLUEPRINT, err, config)

    automation_name = "Unnamed automation"
    if isinstance(config, Mapping):
        if CONF_ALIAS in config:
            automation_name = f"Automation with alias '{config[CONF_ALIAS]}'"
        elif CONF_ID in config:
            automation_name = f"Automation with ID '{config[CONF_ID]}'"

    try:
        validated_config = PLATFORM_SCHEMA(config)
    except vol.Invalid as err:
        _log_invalid_automation(err, automation_name, "could not be validated", config)
        if raise_on_errors:
            raise
        return _minimal_config(ValidationStatus.FAILED_SCHEMA, err, config)

    automation_config = AutomationConfig(validated_config)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Open the failing automation in the UI and compare its inputs against the blueprint's current input definitions; add the missing input(s).
2. If the blueprint was updated, re-apply it or edit the raw automations.yaml so every !input placeholder used by the blueprint is supplied.
3. Blueprint authors: give inputs sensible defaults in the blueprint YAML so existing automations keep working after schema changes.
4. If you rely on programmatic setup, catch HomeAssistantError around setup and inspect err.__cause__ (UndefinedSubstitution) to report which substitution failed.

Example fix

# before (blueprint uses !input notify_service but automation omits it)
input: {}
# after
input:
  notify_service: notify.mobile_app

from homeassistant.helpers.blueprint import BlueprintInputs

def missing_inputs(blueprint_inputs: BlueprintInputs) -> set[str]:
    import homeassistant.helpers.config_validation as cv
    # Render the blueprint domain and diff required !input placeholders vs provided inputs
    raw = blueprint_inputs.blueprint.domain  # blueprint raw config lives on the blueprint object
    provided = set(blueprint_inputs.inputs)
    # Use the blueprint's input schema to find required keys without defaults
    schema = blueprint_inputs.blueprint.metadata.get("input", {})
    return {k for k, spec in schema.items() if "default" not in spec} - provided

from homeassistant.exceptions import HomeAssistantError
from homeassistant.helpers.blueprint import UndefinedSubstitution

try:
    config = blueprint_inputs.async_substitute()
except UndefinedSubstitution as err:
    # report which placeholder/input is missing instead of loading a broken automation
    report(err)

When it happens

Trigger: Calling automation async_setup or validating a blueprint-based automation config where blueprint_inputs.async_substitute() encounters a placeholder in the blueprint YAML with no corresponding value in the provided inputs; e.g. an input key was renamed in a blueprint update but the automation's stored inputs still use the old key.

Common situations: Blueprint author renamed or removed an input that existing automations reference; user hand-edited automations.yaml and dropped an input; blueprint imported from a community repository changed its schema between versions; input nesting (select/selector) mismatches the blueprint's use of !input.

Related errors

• This alert cannot be acknowledged
• integrations_disabled
• invalid_bucket_name
• No data returned from Azure DevOps
• No valid blueprint found in the topic. Blueprint syntax bloc

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