home-assistant/core · error · AlexaInvalidDirectiveError

INVALID_DIRECTIVE

INVALID_DIRECTIVE

Error message

The unlock directive is not supported for the following locales: {config.locale}

What it means

Home Assistant's Alexa smart home integration only enables the Alexa.UnlockController directive in a whitelist of locales (en-US, de-DE, fr-FR, etc., see the set in handlers.py). When an Unlock directive arrives and hass.config.locale is not in that set, the handler raises AlexaInvalidDirectiveError, which is serialized back to Alexa as an INVALID_DIRECTIVE error response.

Source

Thrown at homeassistant/components/alexa/handlers.py:552

        "en-GB",
        "en-IN",
        "en-US",
        "es-ES",
        "es-MX",
        "es-US",
        "fr-CA",
        "fr-FR",
        "hi-IN",
        "it-IT",
        "ja-JP",
        "nl-NL",
        "pt-BR",
    }:
        msg = (
            "The unlock directive is not supported for the following locales:"
            f" {config.locale}"
        )
        raise AlexaInvalidDirectiveError(msg)

    entity = directive.entity
    await hass.services.async_call(
        entity.domain,
        SERVICE_UNLOCK,
        {ATTR_ENTITY_ID: entity.entity_id},
        blocking=False,
        context=context,
    )

    response = directive.response()
    response.add_context_property(
        {"namespace": "Alexa.LockController", "name": "lockState", "value": "UNLOCKED"}
    )

    return response

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Switch the Home Assistant instance (or the Alexa device) language to a supported locale such as en-US, en-GB, de-DE, fr-FR, fr-CA, hi-IN, it-IT, ja-JP, nl-NL, or pt-BR.
If the locale cannot be changed, remove the lock from Alexa-exposed entities so the unlock directive is never routed to HA.
Verify you are using the official Alexa/SmartThings-style cloud integration, not a stale custom skill with different locale handling.

Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_UNLOCK_LOCALES = {
    'en-US', 'en-GB', 'en-AU', 'en-CA', 'en-IN', 'de-DE',
    'fr-CA', 'fr-FR', 'hi-IN', 'it-IT', 'ja-JP', 'nl-NL', 'pt-BR',
}
if hass.config.language not in SUPPORTED_UNLOCK_LOCALES:
    # do not expose unlock; fall back to lock-only capability
    ...

Type guard

def unlock_supported(hass) -> bool:
    return hass.config.language in {
        'en-US', 'en-GB', 'en-AU', 'en-CA', 'en-IN', 'de-DE',
        'fr-CA', 'fr-FR', 'hi-IN', 'it-IT', 'ja-JP', 'nl-NL', 'pt-BR',
    }

Try / catch

try:
    await handle_directive(directive)
except AlexaInvalidDirectiveError:
    # Alexa already receives INVALID_DIRECTIVE; log locale for diagnosis
    _LOGGER.warning('Unlock rejected for locale %s', hass.config.language)

Prevention

Match HA instance language to an unlock-supported locale before exposing locks.
Hide lock entities from Alexa in unsupported locales so unlock directives never arrive.
Track the supported-locale set in handlers.py when upgrading HA.

When it happens

Trigger: User says 'Alexa, unlock the door' while the Home Assistant instance (or the Alexa communications/configured language) resolves to a locale outside the supported set. The unlock handler is reached, the locale check fails, and the exception is raised.

Common situations: HA instance language set to a locale Amazon has not cleared for unlock (e.g. es-MX, ko-KR), or a mismatch between the Alexa device language and HA's configured language after adding locks. Often appears right after exposing a lock entity to Alexa via the cloud/alexa integration.

Related errors

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