{"record":{"id":"0576d9098aa0cbba","repo":"home-assistant/core","slug":"unsupported-fan-mode-fan-mode","errorCode":null,"errorMessage":"Unsupported fan mode {fan_mode}","messagePattern":"Unsupported fan mode (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"homeassistant/components/aprilaire/climate.py","lineNumber":287,"sourceCode":"\n        await self.coordinator.client.update_setpoint(cool_setpoint, heat_setpoint)\n\n        await self.coordinator.client.read_control()\n\n    @override\n    async def async_set_humidity(self, humidity: int) -> None:\n        \"\"\"Set the target humidification setpoint.\"\"\"\n\n        await self.coordinator.client.set_humidification_setpoint(humidity)\n\n    @override\n    async def async_set_fan_mode(self, fan_mode: str) -> None:\n        \"\"\"Set the fan mode.\"\"\"\n\n        try:\n            fan_mode_value_index = list(FAN_MODE_MAP.values()).index(fan_mode)\n        except ValueError as exc:\n            raise ValueError(f\"Unsupported fan mode {fan_mode}\") from exc\n\n        fan_mode_value = list(FAN_MODE_MAP.keys())[fan_mode_value_index]\n\n        await self.coordinator.client.update_fan_mode(fan_mode_value)\n\n        await self.coordinator.client.read_control()\n\n    @override\n    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:\n        \"\"\"Set the HVAC mode.\"\"\"\n\n        try:\n            mode_value_index = list(HVAC_MODE_MAP.values()).index(hvac_mode)\n        except ValueError as exc:\n            raise ValueError(f\"Unsupported HVAC mode {hvac_mode}\") from exc\n\n        mode_value = list(HVAC_MODE_MAP.keys())[mode_value_index]\n","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/aprilaire/climate.py#L269-L305","documentation":"Raised as ValueError by AprilaireClimateEntity.async_set_fan_mode when the requested fan mode string is not one of the values in FAN_MODE_MAP ({1: FAN_ON, 2: FAN_AUTO, 3: FAN_CIRCULATE}). The entity does not advertise any fan modes, so any mode outside that set cannot be mapped to a protocol value and is rejected before anything is sent to the thermostat.","triggerScenarios":"A climate.set_fan_mode service call (or entity action) targeting an Aprilaire climate entity with fan_mode not equal to 'on', 'auto', or 'circulate'. The list(...).index(fan_mode) lookup raises ValueError which is re-raised with this message.","commonSituations":"Automations or scripts copied from another climate integration that uses modes like 'low'/'medium'/'high'; dashboards exposing generic fan mode dropdowns; scene files restored from a different thermostat brand.","solutions":["Use only 'on', 'auto', or 'circulate' in climate.set_fan_mode calls to Aprilaire entities.","Update the automation/script/scene to map generic fan modes to one of the three supported values before calling the service.","Check that you targeted the right entity_id — other climate entities in the home may accept different modes."],"exampleFix":"# before\naction:\n  - action: climate.set_fan_mode\n    target:\n      entity_id: climate.aprilaire\n    data:\n      fan_mode: \"low\"\n\n# after\naction:\n  - action: climate.set_fan_mode\n    target:\n      entity_id: climate.aprilaire\n    data:\n      fan_mode: \"circulate\"","handlingStrategy":"type-guard","validationCode":"SUPPORTED_FAN_MODES = {\"on\", \"auto\", \"circulate\"}\nif fan_mode not in SUPPORTED_FAN_MODES:\n    _LOGGER.warning(\"Skipping unsupported fan mode %s\", fan_mode)\n    return","typeGuard":"def is_aprilaire_fan_mode(mode: str) -> bool:\n    return mode in {\"on\", \"auto\", \"circulate\"}","tryCatchPattern":"try:\n    await climate_entity.async_set_fan_mode(fan_mode)\nexcept ValueError:\n    # mode not in FAN_MODE_MAP; clamp to 'auto' or surface to user\nraise","preventionTips":["Drive automations from the entity's own supported feature lists, not hardcoded mode names.","Validate fan modes against {'on','auto','circulate'} for Aprilaire entities.","Prefer generic blueprints that read entity attributes before calling services."],"tags":["home-assistant","aprilaire","climate","fan-mode","service-validation"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}