{"record":{"id":"23c576073db11c55","repo":"home-assistant/core","slug":"setup-connection-error-23c576","errorCode":"setup_connection_error","errorMessage":"Failed to retrieve static device data from BSB-LAN device at {host}","messagePattern":"Failed to retrieve static device data from BSB-LAN device at (.+?)","errorType":"exception","errorClass":"ConfigEntryNotReady","httpStatus":null,"severity":"error","filePath":"homeassistant/components/bsblan/__init__.py","lineNumber":197,"sourceCode":"        # Read available heating circuits from config entry data\n        # (populated by config flow or migration)\n        circuits: list[int] = entry.data[CONF_HEATING_CIRCUITS] or list(\n            DEFAULT_HEATING_CIRCUITS\n        )\n\n        # Devices reporting a JSON-API version below v2 operate in a reduced\n        # single-circuit mode. A previously configured entry may still list\n        # additional circuits from when the device ran newer firmware, which\n        # would make setup fail when fetching those now-unsupported circuits.\n        # Restrict to the default single circuit so the integration still loads.\n        if _is_reduced_api_mode(bsblan.json_api_version):\n            circuits = list(DEFAULT_HEATING_CIRCUITS)\n\n        # Fetch device metadata\n        device = await bsblan.device()\n        info = await bsblan.info()\n    except BSBLANConnectionError as err:\n        raise ConfigEntryNotReady(\n            translation_domain=DOMAIN,\n            translation_key=\"setup_connection_error\",\n            translation_placeholders={\"host\": entry.data[CONF_HOST]},\n        ) from err\n    except BSBLANAuthError as err:\n        raise ConfigEntryAuthFailed(\n            translation_domain=DOMAIN,\n            translation_key=\"setup_auth_error\",\n        ) from err\n    except TimeoutError as err:\n        raise ConfigEntryNotReady(\n            translation_domain=DOMAIN,\n            translation_key=\"setup_connection_error\",\n            translation_placeholders={\"host\": entry.data[CONF_HOST]},\n        ) from err\n    except BSBLANVersionError as err:\n        # The device does not report a supported JSON-API version, so the\n        # integration cannot operate. Surface a clear, actionable error.","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/bsblan/__init__.py#L179-L215","documentation":"Raised during bsblan config-entry setup when the initial static-data fetch (`bsblan.device()` / `bsblan.info()`) raises BSBLANConnectionError. It is surfaced as ConfigEntryNotReady with translation key `setup_connection_error` and the configured host placeholder, so HA retries setup with backoff instead of failing permanently. It means TCP-level or HTTP-level communication with the BSB-LAN device could not be established.","triggerScenarios":"Loading a bsblan config entry while the device at `entry.data[CONF_HOST]` is powered off, on a different IP, behind a wrong port, or the ESP/adapter running BSB-LAN is not serving its JSON API. Any BSBLANConnectionError from `bsblan.device()` or `bsblan.info()` during `_async_setup_entry`.","commonSituations":"DHCP lease change after router reboot, device renamed/moved in the network, firewall blocking the port, BSB-LAN firmware device asleep, or wrong host/port in integration options.","solutions":["Ping or open `http://<host>/JQ` in a browser to confirm the BSB-LAN web UI is reachable from the HA host.","Fix the host/IP (set a DHCP reservation) and reload the config entry — ConfigEntryNotReady retries automatically.","Check port and (if configured) user/pass in the integration's reconfigure/options flow.","If the device is briefly offline after power loss, just wait; the entry will retry setup with backoff."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"# pre-flight reachability check before reloading the entry\ncurl -sm 5 \"http://<host>/JQ\" | head -c 200","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Give the BSB-LAN device a DHCP reservation so the host never changes.","Keep the device powered on a UPS if the boiler setup is critical.","Remember ConfigEntryNotReady auto-retries — no need to repeatedly reload."],"tags":["home-assistant","bsblan","network","setup","connection"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}