home-assistant/core · error · AlexaBridgeUnreachableError

BRIDGE_UNREACHABLE

BRIDGE_UNREACHABLE

Error message

Alexa API not enabled in Home Assistant configuration

What it means

Raised in smart_home.py's async_handle_message when the enabled flag is false: the Alexa smart_home API endpoint was disabled in configuration (smart_home: enable: false under the cloud integration), so every directive gets a BRIDGE_UNREACHABLE response naming the disabled API.

Source

Thrown at homeassistant/components/alexa/smart_home.py:207

    context: Context | None = None,
    enabled: bool = True,
) -> dict[str, Any]:
    """Handle incoming API messages.

    If enabled is False, the response to all messages will be a
    BRIDGE_UNREACHABLE error. This can be used if the API has been disabled in
    configuration.
    """
    assert request[API_DIRECTIVE][API_HEADER]["payloadVersion"] == "3"

    if context is None:
        context = Context()

    directive = AlexaDirective(request)

    try:
        if not enabled:
            raise AlexaBridgeUnreachableError(  # noqa: TRY301
                "Alexa API not enabled in Home Assistant configuration"
            )

        await config.set_authorized(True)

        if directive.has_endpoint:
            directive.load_entity(hass, config)

        funct_ref = HANDLERS.get((directive.namespace, directive.name))
        if funct_ref:
            response = await funct_ref(hass, config, directive, context)
            if directive.has_endpoint:
                response.merge_context_properties(directive.endpoint)
        else:
            _LOGGER.warning(
                "Unsupported API request %s/%s", directive.namespace, directive.name
            )
            response = directive.error()

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Set enable: true (or remove the smart_home block) in configuration.yaml and restart Home Assistant
  2. Check Settings -> Cloud -> Alexa to confirm the API is active
  3. Verify YAML indentation of the cloud: smart_home: section after edits

Example fix

# configuration.yaml
# before
cloud:
  smart_home:
    enable: false

# after
cloud:
  smart_home:
    enable: true
Defensive patterns

Strategy: validation

Validate before calling

if not config.should_expose(entity_id):  # proxy for cloud config presence
    _LOGGER.warning('Entity not exposed to Alexa')

Try / catch

Catch AlexaBridgeUnreachableError / detect BRIDGE_UNREACHABLE in responses and alert the user the smart home API is disabled in configuration.

Prevention

When it happens

Trigger: Any Alexa smart home directive while configuration.yaml contains cloud: smart_home: enable: false (or the setting was toggled off), including state reports and discovery.

Common situations: Users disable the Alexa API to troubleshoot, then forget to re-enable; YAML indentation errors leave enable false; remote UI toggle turned it off.

Related errors

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