What causes "Connection failed during firmware update" in home-assistant/core?

Check the device web interface afterwards — the install may have succeeded despite the timeout; verify the firmware version before retrying.

home-assistant/core · error · HomeAssistantError

Connection failed during firmware update

Error message

Connection failed during firmware update

What it means

HomeAssistantError raised by the airos update entity when a firmware update fails with any AirOSException other than authentication — the generic 'update_error' fallback. It covers failures during login setup, the firmware download from Ubiquiti servers, or the install command on the device.

Source

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

    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

Check the device web interface afterwards — the install may have succeeded despite the timeout; verify the firmware version before retrying.
Ensure a stable network path and adequate timeout before retrying the update.
Free device space or pick the correct firmware for the exact model.
Inspect the chained AirOSException in logs to identify download vs install failure.
Retry via the device web UI if the integration path keeps failing.

Defensive patterns

Strategy: try-catch

Type guard

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

Try / catch

try:
    await update_entity.async_install(version=None, backup=False)
except HomeAssistantError as err:
    if getattr(err, "translation_key", None) == "update_error":
        # install may still be running on the device: poll the version instead of retrying
        await asyncio.sleep(300)
        await coordinator.async_request_refresh()

Prevention

Verify the target firmware matches the exact device model before starting an update.
Ensure stable network path and do not power-cycle the device mid-install.
Always check the device's reported firmware version after a timeout — install often completes despite dropped connections.

When it happens

Trigger: async_install's download() or install() raises AirOSConnectionSetupError, AirOSDeviceConnectionError, TimeoutError, or any other AirOSException: device unreachable mid-flow, firmware download interrupted, device refusing install due to low disk/bad image, or timeout while the device upgrades.

Common situations: Unstable link to the device during the long download, device running out of storage for the image, mismatched firmware file for the model, or the device dropping the session while installing (which can also look like a timeout even though the install continues).

Related errors

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