{"record":{"id":"fabe8c6b61b5733a","repo":"home-assistant/core","slug":"unsupported-hvac-mode-hvac-mode","errorCode":null,"errorMessage":"Unsupported HVAC mode {hvac_mode}","messagePattern":"Unsupported HVAC mode (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"homeassistant/components/aprilaire/climate.py","lineNumber":302,"sourceCode":"        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\n        await self.coordinator.client.update_mode(mode_value)\n\n        await self.coordinator.client.read_control()\n\n    @override\n    async def async_set_preset_mode(self, preset_mode: str) -> None:\n        \"\"\"Set the preset mode.\"\"\"\n\n        if preset_mode == PRESET_AWAY:\n            await self.coordinator.client.set_hold(3)\n        elif preset_mode == PRESET_VACATION:\n            await self.coordinator.client.set_hold(4)\n        elif preset_mode == PRESET_NONE:\n            await self.coordinator.client.set_hold(0)\n        else:","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/aprilaire/climate.py#L284-L320","documentation":"Raised as ValueError by AprilaireClimateEntity.async_set_hvac_mode when the requested HVAC mode is not a value in HVAC_MODE_MAP. The entity's hvac_modes attribute is built from that map; passing anything else cannot be translated to the thermostat's protocol mode value and fails before any device command is sent.","triggerScenarios":"A climate.set_hvac_mode service call with an hvac_mode that is not one of the modes exposed by the Aprilaire entity (the values of HVAC_MODE_MAP, e.g. HVACMode.OFF/HEAT/COOL/HEAT_COOL/FAN_ONLY as defined in the component).","commonSituations":"Automations hardcoding modes like 'dry' or 'auto' that the Aprilaire unit does not support; scenes migrated from a heat-pump or multi-mode thermostat; typos in mode strings.","solutions":["Read the entity's supported modes (entity attribute hvac_modes) and use one of those in set_hvac_mode calls.","Fix the automation/script to use a mode the Aprilaire thermostat supports (off/heat/cool/heat_cool per HVAC_MODE_MAP).","Add a Choose/condition so unsupported modes requested by generic blueprints are skipped for Aprilaire entities."],"exampleFix":"# before\naction:\n  - action: climate.set_hvac_mode\n    target:\n      entity_id: climate.aprilaire\n    data:\n      hvac_mode: \"dry\"\n\n# after\naction:\n  - action: climate.set_hvac_mode\n    target:\n      entity_id: climate.aprilaire\n    data:\n      hvac_mode: \"cool\"","handlingStrategy":"type-guard","validationCode":"supported = state.attributes.get(\"hvac_modes\", [])\nif hvac_mode not in supported:\n    _LOGGER.warning(\"%s does not support hvac_mode %s\", entity_id, hvac_mode)\n    return","typeGuard":"from homeassistant.components.climate import HVACMode\n\ndef is_supported_hvac_mode(mode: HVACMode | str) -> bool:\n    return mode in set(HVAC_MODE_MAP.values())  # aprilaire's local map","tryCatchPattern":"try:\n    await climate_entity.async_set_hvac_mode(hvac_mode)\nexcept ValueError:\n    # fall back to a known-supported mode or notify\nraise","preventionTips":["Read the entity's hvac_modes attribute before issuing set_hvac_mode.","Do not copy mode strings between integrations without mapping.","In blueprints, gate mode choices per-entity via templates."],"tags":["home-assistant","aprilaire","climate","hvac-mode","service-validation"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}