{"record":{"id":"3d377983d7789b4b","repo":"home-assistant/core","slug":"timeout-connecting-to-caldav-server","errorCode":null,"errorMessage":"Timeout connecting to CalDAV server","messagePattern":"Timeout connecting to CalDAV server","errorType":"exception","errorClass":"ConfigEntryNotReady","httpStatus":null,"severity":"warning","filePath":"homeassistant/components/caldav/__init__.py","lineNumber":49,"sourceCode":"    \"\"\"Set up CalDAV from a config entry.\"\"\"\n    client = caldav.DAVClient(\n        entry.data[CONF_URL],\n        username=entry.data[CONF_USERNAME],\n        password=entry.data[CONF_PASSWORD],\n        ssl_verify_cert=entry.data[CONF_VERIFY_SSL],\n        timeout=TIMEOUT,\n    )\n    try:\n        await hass.async_add_executor_job(client.principal)\n    except AuthorizationError as err:\n        if err.reason == \"Unauthorized\":\n            raise ConfigEntryAuthFailed(\"Credentials error from CalDAV server\") from err\n        # AuthorizationError can be raised if the url is incorrect or\n        # on some other unexpected server response.\n        _LOGGER.warning(\"Unexpected CalDAV server response: %s\", err)\n        return False\n    except requests.Timeout as err:\n        raise ConfigEntryNotReady(\"Timeout connecting to CalDAV server\") from err\n    except requests.ConnectionError as err:\n        raise ConfigEntryNotReady(\"Connection error from CalDAV server\") from err\n    except DAVError as err:\n        raise ConfigEntryNotReady(\"CalDAV client error\") from err\n\n    entry.runtime_data = client\n\n    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)\n\n    return True\n\n\nasync def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:\n    \"\"\"Unload a config entry.\"\"\"\n    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)\n","sourceCodeStart":31,"sourceCodeEnd":65,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/caldav/__init__.py#L31-L65","documentation":"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.","triggerScenarios":"The initial principal() request exceeds the client TIMEOUT (passed to caldav.DAVClient) because the server is slow, unreachable, or the network drops packets.","commonSituations":"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.","solutions":["Verify server reachability from the HA host (curl -m 30 the CalDAV URL)","Wait for the automatic retry — transient startup ordering issues (server boots slower than HA) resolve themselves","Check reverse proxy / firewall timeouts if the server is behind one","If the server is persistently slow, address server performance (database, PHP workers for Nextcloud)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"except requests.Timeout as err:\n    raise ConfigEntryNotReady(\"Timeout connecting to CalDAV server\") from err","preventionTips":["Ensure the CalDAV server is up before HA restarts (startup ordering)","Keep server latency low enough to fit the client timeout","Rely on ConfigEntryNotReady backoff instead of manual reboots"],"tags":["homeassistant","caldav","timeout","network","config-entry"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}