home-assistant/core · error · ConfigEntryAuthFailed

Migration to OAuth required

Error message

Migration to OAuth required

What it means

ConfigEntryAuthFailed('Migration to OAuth required') raised by August's async_setup_entry when the stored config entry data lacks the 'auth_implementation' key — the signature of a legacy username/password entry created before the integration moved to OAuth. Raising ConfigEntryAuthFailed makes HA immediately put the entry into reauth-setup-failed state and surface a reauthenticate flow to the user.

Source

Thrown at homeassistant/components/august/__init__.py:40

    ImplementationUnavailableError,
    OAuth2Session,
    async_get_config_entry_implementation,
)

from .const import DEFAULT_AUGUST_BRAND, DOMAIN, PLATFORMS
from .data import AugustData
from .gateway import AugustGateway
from .util import async_create_august_clientsession

type AugustConfigEntry = ConfigEntry[AugustData]


async def async_setup_entry(hass: HomeAssistant, entry: AugustConfigEntry) -> bool:
    """Set up August from a config entry."""
    # Check if this is a legacy config entry that needs migration to OAuth
    if "auth_implementation" not in entry.data:
        # This is a legacy entry using username/password, trigger reauth
        raise ConfigEntryAuthFailed("Migration to OAuth required")

    session = async_create_august_clientsession(hass)
    try:
        implementation = await async_get_config_entry_implementation(hass, entry)
    except ImplementationUnavailableError as err:
        raise ConfigEntryNotReady("OAuth implementation not available") from err
    oauth_session = OAuth2Session(hass, entry, implementation)
    august_gateway = AugustGateway(Path(hass.config.config_dir), session, oauth_session)
    try:
        await async_setup_august(hass, entry, august_gateway)
    except OAuth2TokenRequestReauthError as err:
        raise ConfigEntryAuthFailed from err
    except (RequireValidation, InvalidAuth) as err:
        raise ConfigEntryAuthFailed from err
    except TimeoutError as err:
        raise ConfigEntryNotReady("Timed out connecting to august api") from err
    except (
        AugustApiAIOHTTPError,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Open the reauth prompt (Settings > Devices & Services > August > Reauthenticate) and complete OAuth login with your August/Yale account
2. If no prompt appears, remove the August entry and set it up fresh
3. Ensure the account owner can log in to the August app (OAuth requires valid credentials + 2FA device)

if "auth_implementation" not in entry.data:
    # legacy entry: start reauth before attempting setup
    await hass.config_entries.async_start_reauth(hass, context={"source": "reauth"})

When it happens

Trigger: Upgrading Home Assistant from a version where August used email/password login; importing an old august config entry from a backup; any entry created before the OAuth migration ships.

Common situations: Post-upgrade first boot of an HA instance with a long-standing August integration; restored configuration database from an older HA version.

Related errors

• OAuth implementation not available
• Invalid credentials: {ex}
• auth_error
• auth_expired
• auth_expired

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