home-assistant/core · error · ConfigEntryError

setup_outdated_firmware

setup_outdated_firmware

Error message

Your BSB-LAN device is running firmware {firmware_version}, which is no longer supported. Please update your BSB-LAN board firmware to a newer version to keep using this integration.

What it means

Raised during bsblan setup when the device reports a JSON-API version python-bsblan does not support (BSBLANVersionError), mapped to ConfigEntryError with translation key `setup_outdated_firmware` and the device's firmware version (or 'unknown' if unavailable). Unlike NotReady errors, this is a hard failure: the integration cannot operate until the BSB-LAN firmware is updated. A repair issue is also created recommending the upgrade.

Source

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

            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.
        firmware_version = bsblan.device_info.version if bsblan.device_info else None
        raise ConfigEntryError(
            translation_domain=DOMAIN,
            translation_key="setup_outdated_firmware",
            translation_placeholders={
                "firmware_version": firmware_version or "unknown"
            },
        ) from err
    except BSBLANError as err:
        raise ConfigEntryError(
            translation_domain=DOMAIN,
            translation_key="setup_general_error",
        ) from err

    # Devices below JSON-API v2 operate with a reduced single-circuit feature
    # set. Surface (or clear) the repair issue recommending a firmware upgrade.
    _async_manage_outdated_firmware_issue(
        hass, entry, device.version, bsblan.json_api_version
    )

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Update the BSB-LAN firmware on the device (see bsblan.friedrich-programme.de docs) to a version with a supported JSON API.
Reload the integration after the firmware update; if a repair issue exists, it clears automatically.
If firmware is already newest and the error persists, the HA bsblan integration/python-bsblan may lag behind — update Home Assistant to get a newer library.

Defensive patterns

Strategy: validation

Validate before calling

# confirm the device's JSON API version before adding the entry
import bsblan
client = bsblan.BSBLan(host, user, pass_)
print(await client.api_version())

Prevention

Check the BSB-LAN release notes for supported JSON API versions before updating HA or firmware.
Update BSB-LAN firmware promptly when the integration's minimum supported version changes.
Read the repair issue HA raises — it names the exact firmware version needed.

When it happens

Trigger: Loading a bsblan entry against a board running firmware so old that its JSON API version is below what the python-bsblan library supports (or a brand-new API version the library has not learned yet). `bsblan.device_info.version` is used for the placeholder when already fetched.

Common situations: Users who installed BSB-LAN years ago and never updated the sketch; a newly flashed device with an old saved config; or conversely a brand-new firmware ahead of the pinned python-bsblan release.

Related errors

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