home-assistant/core · error · ConfigEntryError

ConfigEntryError

Error message

ConfigEntryError

What it means

ConfigEntryError is Home Assistant's non-retriable setup error: the entry goes into a failed state requiring user action (no automatic retries). The blebox integration raises it when Box.async_from_host() fails with the library's base Error that is neither UnauthorizedRequest nor ConnectionError/HttpError — typically an unsupported or malformed device response (e.g. the /api/device/product API returned data the library cannot parse).

Source

Thrown at homeassistant/components/blebox/__init__.py:61

    password = entry.data.get(CONF_PASSWORD)

    timeout = DEFAULT_SETUP_TIMEOUT

    websession = get_maybe_authenticated_session(hass, password, username)

    api_host = ApiHost(host, port, timeout, websession, hass.loop)

    try:
        product = await Box.async_from_host(api_host)
    except UnauthorizedRequest as ex:
        raise ConfigEntryAuthFailed from ex
    except (
        ConnectionError,
        HttpError,
    ) as ex:
        raise ConfigEntryNotReady from ex
    except Error as ex:
        raise ConfigEntryError from ex

    coordinator = BleBoxCoordinator(hass, entry, product)
    await coordinator.async_config_entry_first_refresh()

    entry.runtime_data = coordinator

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)

    return True


async def async_unload_entry(hass: HomeAssistant, entry: BleBoxConfigEntry) -> bool:
    """Unload a config entry."""
    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify the host actually is a BleBox device: open http://<host>/api/device/product and check the response.
2. Update (or align) the `blebox-unofficial-api` package version to one supporting your firmware, and update HA core.
3. Power-cycle the device and reload the entry — a wedged controller can emit malformed responses.
4. If the device is genuinely unsupported, remove the config entry; ConfigEntryError will not self-heal by retrying.
5. Report the product JSON (from step 1) to the blebox_unofficial-api maintainers if firmware drift is confirmed.

import aiohttp

async def is_blebox_device(session: aiohttp.ClientSession, host: str) -> bool:
    """Confirm the endpoint is a parseable BleBox before adding it."""
    async with session.get(f"http://{host}/api/device/product") as resp:
        if resp.status != 200:
            return False
        data = await resp.json(content_type=None)
        return all(k in data for k in ("id", "type", "apiLevel"))

try:
    product = await Box.async_from_host(api_host)
except Error as ex:  # after Unauthorized/Connection/Http branches
    raise ConfigEntryError from ex  # permanent: needs user action

When it happens

Trigger: async_from_host fetches product info and the blebox_unofficial library raises a plain Error subclass — unsupported product type, unexpected/missing fields in the device's JSON, or an API shape from newer firmware the installed library version doesn't understand.

Common situations: Newer device firmware changing API responses beyond the pinned blebox-unofficial-api version, pointing the integration at a non-BleBox device on the same IP, partially failed device firmware returning truncated JSON.

Related errors

• Credential is already linked to a user
• System generated users cannot disable multi-factor auth modu
• Invalid authentication
• Cannot delete credential in use by integration {entry.domain
• Authentication failed, please check credentials

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