home-assistant/core · error · HomeAssistantError

invalid_auth

invalid_auth

Error message

Invalid authentication credentials: {error}

What it means

Raised as a HomeAssistantError (translation key alexa_devices/invalid_auth) when the underlying alexapy client signals CannotAuthenticate during an Alexa API call wrapped by the alexa_api_call context manager. It means Amazon rejected the stored authentication cookies/tokens, so the API call cannot proceed. The coordinator is also flagged as failed (last_update_success = False) so entities show unavailable.

Source

Thrown at homeassistant/components/alexa_devices/coordinator.py:53

from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
from homeassistant.util import slugify

from .const import CONF_LOGIN_DATA, DOMAIN, LOGGER

SCAN_INTERVAL = 300


@asynccontextmanager
async def alexa_api_call(
    coordinator: DataUpdateCoordinator | None = None,
) -> AsyncGenerator[None]:
    """Handle common Alexa API exceptions as HomeAssistantError."""
    try:
        yield
    except CannotAuthenticate as err:
        if coordinator:
            coordinator.last_update_success = False
        raise HomeAssistantError(
            translation_domain=DOMAIN,
            translation_key="invalid_auth",
            translation_placeholders={"error": repr(err)},
        ) from err
    except CannotConnect as err:
        if coordinator:
            coordinator.last_update_success = False
        raise HomeAssistantError(
            translation_domain=DOMAIN,
            translation_key="cannot_connect_with_error",
            translation_placeholders={"error": repr(err)},
        ) from err
    except (CannotRetrieveData, ValueError) as err:
        if coordinator:
            coordinator.last_update_success = False
        raise HomeAssistantError(
            translation_domain=DOMAIN,
            translation_key="cannot_retrieve_data_with_error",

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Trigger the reauth config flow for the alexa_devices config entry (UI will show a reauthentication prompt) and log in to Amazon again to store fresh cookies
2. Verify the Amazon account password was not changed and no suspicious-login lockout exists on the Amazon side
3. If 2FA/CAPTCHA is involved, complete the interactive login in the config flow so the OTP is captured
4. Restart Home Assistant after successful reauth so coordinators rebuild with the new session

try:
    async with alexa_api_call():
        await coordinator.api.some_call(...)
except HomeAssistantError as err:
    if err.translation_key == "invalid_auth":
        # surface reauth to the user; stop retrying
        _LOGGER.warning("Alexa session expired: %s", err)
    else:
        raise

When it happens

Trigger: Any coordinator or service code path that runs inside `async with alexa_api_call(...)` (entity actions, media commands, notifications) when alexapy raises CannotAuthenticate — typically expired Amazon cookies, a changed account password, or Amazon presenting a CAPTCHA/2FA challenge during the request.

Common situations: Long-running installations whose Amazon session cookies expire (~every few weeks), users who changed their Amazon password or revoked sessions, logins from a new region triggering Amazon security challenges, or two-factor prompts that the stored session cannot answer.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• cannot_connect_with_error
• cannot_retrieve_data_with_error
• invalid_device_id
• entry_not_loaded
• config_entry_not_found

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