home-assistant/core · error · UpdateFailed

coordinator_state_error

coordinator_state_error

Error message

Error while fetching state data for heating circuit {circuit} from the BSB-LAN device at {host}

What it means

Raised by the bsblan DataUpdateCoordinator when fetching state for one heating circuit via `client.state(include=STATE_INCLUDE, circuit=circuit)` raises a BSBLANError that is not auth or connection related. It becomes UpdateFailed with translation key `coordinator_state_error` plus host and circuit placeholders, marking entities unavailable and showing the message in the integration's update error banner. Note the deliberate `except BSBLANAuthError, BSBLANConnectionError: raise` (Python 3.14 unparenthesized form) so those propagate to their own handlers.

Source

Thrown at homeassistant/components/bsblan/coordinator.py:124

    @override
    async def _async_update_data(self) -> BSBLanFastData:
        """Fetch fast-changing data from the BSB-LAN device."""
        states: dict[int, State] = {}
        host = self.config_entry.data[CONF_HOST]
        try:
            # Use include filtering to only fetch parameters we actually use.
            # BSB-LAN is a serial bus — it processes one parameter at a time,
            # so concurrent requests offer no speed benefit over sequential.
            for circuit in self.circuits:
                try:
                    states[circuit] = await self.client.state(
                        include=STATE_INCLUDE, circuit=circuit
                    )
                except BSBLANAuthError, BSBLANConnectionError:
                    raise
                except BSBLANError as err:
                    raise UpdateFailed(
                        translation_domain=DOMAIN,
                        translation_key="coordinator_state_error",
                        translation_placeholders={
                            "host": host,
                            "circuit": str(circuit),
                        },
                    ) from err
            sensor = await self.client.sensor(include=SENSOR_INCLUDE)

        except BSBLANAuthError as err:
            raise ConfigEntryAuthFailed(
                translation_domain=DOMAIN,
                translation_key="coordinator_auth_error",
            ) from err
        except BSBLANConnectionError as err:
            raise UpdateFailed(
                translation_domain=DOMAIN,
                translation_key="coordinator_connection_error",

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Check the circuit number in the error against circuits actually present on the boiler; remove stale circuits by reconfiguring the entry.
  2. Reload/re-pair after a firmware update so the circuit list matches the device's current JSON API version.
  3. If transient, the next scheduled coordinator refresh clears it; reduce external polling that contends on the serial bus.
  4. Enable debug logging to capture the underlying BSBLANError for the failing circuit.
Defensive patterns

Strategy: try-catch

Try / catch

try:
    states[circuit] = await client.state(include=STATE_INCLUDE, circuit=circuit)
except BSBLANAuthError, BSBLANConnectionError:
    raise
except BSBLANError as err:
    raise UpdateFailed(...) from err

Prevention

When it happens

Trigger: A coordinator refresh where exactly one circuit's state query fails — e.g. the configured circuit does not exist on the device, the include parameters are rejected, or a malformed response for that circuit.

Common situations: Multi-circuit setups where one circuit was removed/re-wired, devices in reduced single-circuit API mode still listing an extra circuit, or transient malformed JSON for one bus read.

Related errors

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