home-assistant/core · error · HomeAssistantError

command_failed

command_failed

Error message

Failed to execute command on the BleBox device: {error}

What it means

The @blebox_command decorator (util.py) wraps every BleBox entity command; if the python-blebox library raises Error while executing the command, it is converted to HomeAssistantError with key 'command_failed' ('Failed to execute command on the BleBox device: {error}'). After the raise, the finally block still refreshes the coordinator so state stays in sync. This is the generic failure path for most blebox entity actions (turn_on, turn_off, set positions, etc.).

Source

Thrown at homeassistant/components/blebox/util.py:26

from homeassistant.exceptions import HomeAssistantError

from .const import DOMAIN
from .entity import BleBoxEntity


def blebox_command[_BleBoxEntityT: BleBoxEntity, **_P, _R](
    func: Callable[Concatenate[_BleBoxEntityT, _P], Awaitable[_R]],
) -> Callable[Concatenate[_BleBoxEntityT, _P], Coroutine[Any, Any, _R]]:
    """Decorate BleBox calls that send commands to the device.

    Catches BleBox errors and refreshes the coordinator after the command.
    """

    async def handler(self: _BleBoxEntityT, *args: _P.args, **kwargs: _P.kwargs) -> _R:
        try:
            return await func(self, *args, **kwargs)
        except Error as err:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="command_failed",
                translation_placeholders={"error": str(err)},
            ) from err
        finally:
            await self.coordinator.async_refresh()

    return handler

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify device reachability (ping or open its web UI).
2. Fix addressing with a DHCP reservation if the IP roams.
3. Space out rapid-fire commands from automations (the embedded server handles one request at a time).
4. Update the integration and python-blebox library, then retry the action.

if not coordinator.last_update_success:
    _LOGGER.warning("Skipping command; device unreachable")
    return

from homeassistant.exceptions import HomeAssistantError

try:
    await entity.async_turn_on(**kwargs)
except HomeAssistantError as err:
    if err.translation_key == "command_failed":
        _LOGGER.warning("BleBox command failed (device likely offline): %s", err)

When it happens

Trigger: Any blebox entity action whose underlying HTTP API call fails: device offline, timeout, connection reset, or gateway error. The command never reached or was not accepted by the device.

Common situations: Device powered off or unreachable; IP changed after DHCP lease renewal; slow device that misses the HTTP timeout; multiple rapid commands overwhelming the small embedded webserver.

Related errors

• data_update_failed
• update_failed
• Credential is already linked to a user
• Unable find multi-factor auth module: {mfa_module_id}
• update_error

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