{"record":{"id":"d30b70b572a5accf","repo":"home-assistant/core","slug":"command-failed","errorCode":"command_failed","errorMessage":"Failed to execute command on the BleBox device: {error}","messagePattern":"Failed to execute command on the BleBox device: (.+?)","errorType":"exception","errorClass":"HomeAssistantError","httpStatus":null,"severity":"error","filePath":"homeassistant/components/blebox/util.py","lineNumber":26,"sourceCode":"from homeassistant.exceptions import HomeAssistantError\n\nfrom .const import DOMAIN\nfrom .entity import BleBoxEntity\n\n\ndef blebox_command[_BleBoxEntityT: BleBoxEntity, **_P, _R](\n    func: Callable[Concatenate[_BleBoxEntityT, _P], Awaitable[_R]],\n) -> Callable[Concatenate[_BleBoxEntityT, _P], Coroutine[Any, Any, _R]]:\n    \"\"\"Decorate BleBox calls that send commands to the device.\n\n    Catches BleBox errors and refreshes the coordinator after the command.\n    \"\"\"\n\n    async def handler(self: _BleBoxEntityT, *args: _P.args, **kwargs: _P.kwargs) -> _R:\n        try:\n            return await func(self, *args, **kwargs)\n        except Error as err:\n            raise HomeAssistantError(\n                translation_domain=DOMAIN,\n                translation_key=\"command_failed\",\n                translation_placeholders={\"error\": str(err)},\n            ) from err\n        finally:\n            await self.coordinator.async_refresh()\n\n    return handler\n","sourceCodeStart":8,"sourceCodeEnd":35,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/blebox/util.py#L8-L35","documentation":"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.).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify device reachability (ping or open its web UI).","Fix addressing with a DHCP reservation if the IP roams.","Space out rapid-fire commands from automations (the embedded server handles one request at a time).","Update the integration and python-blebox library, then retry the action."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if not coordinator.last_update_success:\n    _LOGGER.warning(\"Skipping command; device unreachable\")\n    return","typeGuard":null,"tryCatchPattern":"from homeassistant.exceptions import HomeAssistantError\n\ntry:\n    await entity.async_turn_on(**kwargs)\nexcept HomeAssistantError as err:\n    if err.translation_key == \"command_failed\":\n        _LOGGER.warning(\"BleBox command failed (device likely offline): %s\", err)","preventionTips":["Check coordinator health (last_update_success) before firing commands.","Rate-limit automations that hammer BleBox devices with rapid commands."],"tags":["home-assistant","blebox","command","network"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}