home-assistant/core · error · ConfigEntryError

setup_general_error

setup_general_error

Error message

An unknown error occurred while retrieving static device data

What it means

Catch-all raised during bsblan setup when the static-data fetch raises a generic BSBLANError that is not a connection, auth, timeout, or version problem. It is raised as ConfigEntryError with translation key `setup_general_error`, a terminal failure state (no automatic retry), so the user must intervene. It usually indicates malformed API responses or unexpected library-level failures.

Source

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

    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
    )

    # Fetch static values per configured circuit.
    # BSB-LAN is a serial bus — it processes one parameter at a time,
    # so concurrent requests offer no speed benefit over sequential.
    # Static values are optional — some devices may not support them.
    static_per_circuit: dict[int, StaticState | None] = {}
    for circuit in circuits:
        try:
            static_per_circuit[circuit] = await bsblan.static_values(circuit=circuit)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Open `http://<host>/JQ` and `http://<host>/JI` in a browser and confirm valid JSON comes back.
  2. Reboot the BSB-LAN device (power cycle the board) to clear wedged state, then reload the entry.
  3. Update both BSB-LAN firmware and Home Assistant so client and device API versions match.
  4. Enable debug logging for bsblan and file an issue with the traceback if JSON looks valid.
Defensive patterns

Strategy: try-catch

Validate before calling

# verify the endpoints return real JSON before setup
curl -s "http://<host>/JI" | python3 -m json.tool > /dev/null && echo ok

Try / catch

if entry.state is ConfigEntryState.SETUP_ERROR:
    # inspect the setup error and device manually; ConfigEntryError does not retry
    ...

Prevention

When it happens

Trigger: Loading a bsblan entry where `bsblan.device()` or `bsblan.info()` parses a malformed JSON payload, hits an unexpected HTTP status, or any other BSBLANError subclass not caught by earlier handlers.

Common situations: A proxy or captive portal returning HTML instead of JSON at the configured host, corrupted device responses, partial firmware flashes, or python-bsblan/library and firmware API mismatches.

Related errors

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