home-assistant/core · warning · ConfigEntryNotReady

Timeout connecting to CalDAV server

Error message

Timeout connecting to CalDAV server

What it means

ConfigEntryNotReady raised when client.principal() raises requests.Timeout during CalDAV setup. Home Assistant marks the entry as setup-retry and schedules a retry with exponential backoff; the integration stays unloaded until a retry succeeds.

Source

Thrown at homeassistant/components/caldav/__init__.py:49

    """Set up CalDAV from a config entry."""
    client = caldav.DAVClient(
        entry.data[CONF_URL],
        username=entry.data[CONF_USERNAME],
        password=entry.data[CONF_PASSWORD],
        ssl_verify_cert=entry.data[CONF_VERIFY_SSL],
        timeout=TIMEOUT,
    )
    try:
        await hass.async_add_executor_job(client.principal)
    except AuthorizationError as err:
        if err.reason == "Unauthorized":
            raise ConfigEntryAuthFailed("Credentials error from CalDAV server") from err
        # AuthorizationError can be raised if the url is incorrect or
        # on some other unexpected server response.
        _LOGGER.warning("Unexpected CalDAV server response: %s", err)
        return False
    except requests.Timeout as err:
        raise ConfigEntryNotReady("Timeout connecting to CalDAV server") from err
    except requests.ConnectionError as err:
        raise ConfigEntryNotReady("Connection error from CalDAV server") from err
    except DAVError as err:
        raise ConfigEntryNotReady("CalDAV client error") from err

    entry.runtime_data = client

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)

    return True


async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Unload a config entry."""
    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify server reachability from the HA host (curl -m 30 the CalDAV URL)
2. Wait for the automatic retry — transient startup ordering issues (server boots slower than HA) resolve themselves
3. Check reverse proxy / firewall timeouts if the server is behind one
4. If the server is persistently slow, address server performance (database, PHP workers for Nextcloud)

except requests.Timeout as err:
    raise ConfigEntryNotReady("Timeout connecting to CalDAV server") from err

When it happens

Trigger: The initial principal() request exceeds the client TIMEOUT (passed to caldav.DAVClient) because the server is slow, unreachable, or the network drops packets.

Common situations: Slow or overloaded self-hosted CalDAV servers (Baïkal, Radicale, Nextcloud), reverse proxies with long TLS handshakes, DNS issues, or the host being down at HA startup.

Understand the failure class

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

Related errors

• Connection error from CalDAV server
• Timed out connecting to august api
• Credentials error from CalDAV server
• CalDAV client error
• CalDAV lookup error: {err}

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