home-assistant/core · error · HomeAssistantError

Authentication or connection failed during firmware update

Error message

Authentication or connection failed during firmware update

What it means

HomeAssistantError raised by the airos update entity when a firmware update installation fails specifically at authentication: the AirOSConnectionAuthenticationError path. Login to the device succeeded earlier is not assumed — the update flow re-logs in, and if credentials are rejected, the user sees this localized 'authentication or connection failed during firmware update' message.

Source

Thrown at homeassistant/components/airos/update.py:95

    def release_url(self) -> str | None:
        """Return the release url of the latest firmware."""
        return self.firmware.data.get("changelog")

    @override
    async def async_install(
        self,
        version: str | None,
        backup: bool,
        **kwargs: Any,
    ) -> None:
        """Handle the firmware update installation."""
        _LOGGER.debug("Starting firmware update")
        try:
            await self.status.airos_device.login()
            await self.status.airos_device.download()
            await self.status.airos_device.install()
        except AirOSConnectionAuthenticationError as err:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="update_connection_authentication_error",
            ) from err
        except AirOSException as err:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="update_error",
            ) from err

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Re-verify the device credentials via its web interface.
Run the re-configuration/re-auth flow for the airos entry in Home Assistant, then retry the update.
Check the chained exception in logs to confirm the step that failed.
Ensure no other session invalidated the login (some airOS versions limit concurrent sessions).

Defensive patterns

Strategy: validation

Type guard

def is_airos_update_auth_error(err: Exception) -> bool:
    return isinstance(err, HomeAssistantError) and getattr(err, "translation_domain", None) == "airos" and getattr(err, "translation_key", None) == "update_connection_authentication_error"

Try / catch

try:
    await update_entity.async_install(version=None, backup=False)
except HomeAssistantError as err:
    if getattr(err, "translation_key", None) == "update_connection_authentication_error":
        # re-auth required before any retry
        await start_reauth_flow()

Prevention

Run the re-auth flow for airos as soon as device credentials change, before invoking update actions.
Limit concurrent admin sessions on the airOS device so the integration's login is not evicted.

When it happens

Trigger: async_install calls login(), download(), install(); login() (or an auth-protected step) raises AirOSConnectionAuthenticationError because the stored credentials were rejected by the device.

Common situations: Password changed on the device after the config entry was created, session/cookie invalidated mid-flow, or a firmware image requiring re-authentication on a management port with different credentials.

Understand the failure class

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

Related errors

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