home-assistant/core · error · ConfigEntryNotReady

setup_connection_error

setup_connection_error

Error message

Failed to retrieve static device data from BSB-LAN device at {host}

What it means

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.

Source

Thrown at homeassistant/components/bsblan/__init__.py:197

        # Read available heating circuits from config entry data
        # (populated by config flow or migration)
        circuits: list[int] = entry.data[CONF_HEATING_CIRCUITS] or list(
            DEFAULT_HEATING_CIRCUITS
        )

        # Devices reporting a JSON-API version below v2 operate in a reduced
        # single-circuit mode. A previously configured entry may still list
        # additional circuits from when the device ran newer firmware, which
        # would make setup fail when fetching those now-unsupported circuits.
        # Restrict to the default single circuit so the integration still loads.
        if _is_reduced_api_mode(bsblan.json_api_version):
            circuits = list(DEFAULT_HEATING_CIRCUITS)

        # Fetch device metadata
        device = await bsblan.device()
        info = await bsblan.info()
    except BSBLANConnectionError as err:
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="setup_connection_error",
            translation_placeholders={"host": entry.data[CONF_HOST]},
        ) from err
    except BSBLANAuthError as err:
        raise ConfigEntryAuthFailed(
            translation_domain=DOMAIN,
            translation_key="setup_auth_error",
        ) from err
    except TimeoutError as err:
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="setup_connection_error",
            translation_placeholders={"host": entry.data[CONF_HOST]},
        ) from err
    except BSBLANVersionError as err:
        # The device does not report a supported JSON-API version, so the
        # integration cannot operate. Surface a clear, actionable error.

View on GitHub (pinned to 58a3fdb3ea)

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.

Defensive patterns

Strategy: retry

Validate before calling

# pre-flight reachability check before reloading the entry
curl -sm 5 "http://<host>/JQ" | head -c 200

Prevention

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.

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

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