home-assistant/core · error · ConfigEntryAuthFailed

setup_auth_error

setup_auth_error

Error message

Authentication failed while retrieving static device data

What it means

Raised during bsblan config-entry setup when the static-data fetch raises BSBLANAuthError, i.e. the BSB-LAN device answered but rejected the configured credentials (HTTP 401/403 from the python-bsblan library). It is raised as ConfigEntryAuthFailed with translation key `setup_auth_error`, which forces the config entry into the re-auth flow so the user is prompted for a new password.

Source

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

        # 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.
        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"

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Follow the re-auth prompt that appears on the integration card and re-enter the correct username/password.
Verify the same credentials work by logging into `http://<host>/` in a browser.
If auth style changed after a firmware update, reconfigure the entry (delete and re-add) so the right fields are stored.

Defensive patterns

Strategy: validation

Prevention

Keep BSB-LAN web credentials stable, or update the HA entry immediately after changing them.
Test credentials in the browser before entering them in the config flow.
Respond to the re-auth prompt promptly; entities stay unavailable until resolved.

When it happens

Trigger: Loading a bsblan entry where the device has HTTP basic auth enabled and the stored user/pass is wrong, was changed on the device, or the passkey/API-password scheme changed after a firmware update.

Common situations: User changed the BSB-LAN web password in the device's config; migrated device settings; firmware update changed auth from user/pass to API key or vice versa; typo during initial setup that only fails on protected endpoints.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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