home-assistant/core · error · HomeAssistantError

Failed to install update: {err}

Error message

Failed to install update: {err}

What it means

HomeAssistantError raised by AdGuardUpdate.async_install when adguard.update.begin_update() throws AdGuardHomeError. It aborts the update-install action with a raw f-string message (no translation key) and — importantly — the config-entry reload scheduled on the following line never runs because the exception propagates first.

Source

Thrown at homeassistant/components/adguard/update.py:70

    @override
    async def _adguard_update(self) -> None:
        """Update AdGuard Home entity."""
        value = await self.adguard.update.update_available()
        self._attr_installed_version = self.data.version
        self._attr_latest_version = value.new_version
        self._attr_release_summary = value.announcement
        self._attr_release_url = value.announcement_url

    @override
    async def async_install(
        self, version: str | None, backup: bool, **kwargs: Any
    ) -> None:
        """Install latest update."""
        try:
            await self.adguard.update.begin_update()
        except AdGuardHomeError as err:
            raise HomeAssistantError(f"Failed to install update: {err}") from err
        self.hass.config_entries.async_schedule_reload(self._entry.entry_id)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check the chained AdGuardHomeError in the Home Assistant log for the exact API failure reason.
2. Verify the AdGuard Home host can reach the internet and its update servers (from the AdGuard UI itself, check for updates).
3. If running in Docker, update the container image instead of the in-app updater, or run with the volumes/permissions the updater needs.
4. Retry the install from the AdGuard Home web UI to confirm the server side works, then retry from Home Assistant.
5. Optionally patch the integration to use translation_domain/translation_key like switch.py does, so users get a localized message.

Example fix

// before
try:
    await self.adguard.update.begin_update()
except AdGuardHomeError as err:
    raise HomeAssistantError(f"Failed to install update: {err}") from err

// after
try:
    await self.adguard.update.begin_update()
except AdGuardHomeError as err:
    raise HomeAssistantError(
        translation_domain=DOMAIN,
        translation_key="install_failed",
        translation_placeholders={"error": str(err)},
    ) from err

from homeassistant.exceptions import HomeAssistantError

try:
    await hass.services.async_call(
        "update", "install", {"entity_id": "update.adguard_home"}
    )
except HomeAssistantError as err:
    _LOGGER.error("AdGuard self-update failed: %s", err)  # check chained AdGuardHomeError

When it happens

Trigger: Pressing 'Install' on the AdGuard Home update entity while the server cannot start its self-update: no internet on the AdGuard host, insufficient permissions, or an unsupported update channel/version check failure from the AdGuard API.

Common situations: AdGuard Home running in a container without permission to replace its binary, restricted egress blocking downloads from the AdGuard update servers, or version mismatch where the client's update API call is rejected.

Related errors

• error_while_turn_off
• error_while_turn_on
• config_entry_not_loaded
• update_failed
• {err}

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