home-assistant/core · warning · ConfigEntryNotReady

api_timeout

api_timeout

Error message

Timeout occurred while communicating with the Aqvify API for {entry}

What it means

ConfigEntryNotReady raised during Aqvify coordinator setup (translation_key 'api_timeout') when async_get_account_id() raises TimeoutError — the Aqvify API did not answer in time. Setup is deferred and retried automatically by Home Assistant.

Source

Thrown at homeassistant/components/aqvify/coordinator.py:89

    async def _async_setup(self) -> None:
        """Set up the coordinator."""
        try:
            await self.api_client.async_get_account_id()
        except AqvifyAuthException:
            raise ConfigEntryAuthFailed(
                translation_domain=DOMAIN,
                translation_key="invalid_api_key",
            ) from None
        except ClientResponseError as err:
            raise ConfigEntryNotReady(
                translation_domain=DOMAIN,
                translation_key="api_error",
                translation_placeholders={
                    "entry": self.config_entry.title,
                },
            ) from err
        except TimeoutError as err:
            raise ConfigEntryNotReady(
                translation_domain=DOMAIN,
                translation_key="api_timeout",
                translation_placeholders={
                    "entry": self.config_entry.title,
                },
            ) from err

    @override
    async def _async_update_data(self) -> AqvifyCoordinatorData:
        """Fetch device state."""
        try:
            devices = await self.api_client.async_get_devices()
        except AqvifyAuthException:
            raise ConfigEntryAuthFailed(
                translation_domain=DOMAIN,
                translation_key="invalid_api_key",
            ) from None
        except ClientResponseError as err:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Wait for automatic retry — transient timeouts typically resolve on the next attempt.
Check latency to api.aqvify.com from the HA host (curl/DNS timing); fix network/DNS if consistently slow.
If behind a proxy, bypass or tune it for the Aqvify domain.
Restart the entry from the HA UI (Reload) once the network is confirmed healthy.

Defensive patterns

Strategy: retry

Try / catch

try:
    await asyncio.wait_for(api_client.async_get_account_id(), timeout=15)
except TimeoutError:
    raise ConfigEntryNotReady("Aqvify API timeout") from None

Prevention

Check DNS/proxy health on the HA host when timeouts repeat.
Give the first setup attempt a few automatic retries before intervening.
Avoid overloaded networks/VLANs for the HA host during setup.

When it happens

Trigger: The initial setup request exceeds the aiohttp/HTTP timeout; causes include slow Aqvify servers, packet loss, DNS slowness, or an over-loaded HA host.

Common situations: Temporary cloud latency; restrictive firewall/proxy adding delay to TLS; IPv6 misconfiguration causing connect delays; HA running on resource-starved hardware (Raspberry Pi under load).

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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