home-assistant/core · error · ConfigEntryAuthFailed

{err}

Error message

{err}

What it means

ConfigEntryAuthFailed raised during async_setup_entry when session.async_ensure_token_valid() fails with OAuth2TokenRequestReauthError. HA treats this as 'authentication failed': the refresh token was rejected by the Genie/Aladdin OAuth server, so the entry is put into re-authentication state and the user gets a repair/notification to log in again.

Source

Thrown at homeassistant/components/aladdin_connect/__init__.py:51

    """Set up Aladdin Connect Genie from a config entry."""
    try:
        implementation = (
            await config_entry_oauth2_flow.async_get_config_entry_implementation(
                hass, entry
            )
        )
    except ImplementationUnavailableError as err:
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="oauth2_implementation_unavailable",
        ) from err

    session = config_entry_oauth2_flow.OAuth2Session(hass, entry, implementation)

    try:
        await session.async_ensure_token_valid()
    except OAuth2TokenRequestReauthError as err:
        raise ConfigEntryAuthFailed(err) from err
    except (OAuth2TokenRequestError, aiohttp.ClientError) as err:
        raise ConfigEntryNotReady from err

    client = AladdinConnectClient(
        api.AsyncConfigEntryAuth(aiohttp_client.async_get_clientsession(hass), session)
    )

    coordinator = AladdinConnectCoordinator(hass, entry, client)
    await coordinator.async_config_entry_first_refresh()

    entry.runtime_data = coordinator

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)

    remove_stale_devices(hass, entry)

    return True

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Open Home Assistant, go to the failing Aladdin Connect entry and complete the re-authentication flow.
  2. Verify the account credentials work in the Aladdin Connect app.
  3. If it recurs frequently, check for other clients repeatedly refreshing the same grant.
  4. After re-auth, the entry should leave the failed/auth state automatically.
Defensive patterns

Strategy: try-catch

Try / catch

from homeassistant.exceptions import ConfigEntryAuthFailed

try:
    await session.async_ensure_token_valid()
except OAuth2TokenRequestReauthError as err:
    raise ConfigEntryAuthFailed(err) from err  # HA drives re-auth UI

Prevention

When it happens

Trigger: Expired or revoked refresh token (password changed, token revoked server-side, account linked elsewhere), or the OAuth server responding 400/401 to the refresh grant during setup or a later token refresh.

Common situations: Long-idle install whose refresh token lapsed; user changed their Aladdin Connect account password; sandbox/production client mismatch; server-side cleanup of old grants.

Related errors

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