home-assistant/core · warning · ValueError

Unsupported HVAC mode {hvac_mode}

Error message

Unsupported HVAC mode {hvac_mode}

What it means

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.

Source

Thrown at homeassistant/components/aprilaire/climate.py:302

        try:
            fan_mode_value_index = list(FAN_MODE_MAP.values()).index(fan_mode)
        except ValueError as exc:
            raise ValueError(f"Unsupported fan mode {fan_mode}") from exc

        fan_mode_value = list(FAN_MODE_MAP.keys())[fan_mode_value_index]

        await self.coordinator.client.update_fan_mode(fan_mode_value)

        await self.coordinator.client.read_control()

    @override
    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
        """Set the HVAC mode."""

        try:
            mode_value_index = list(HVAC_MODE_MAP.values()).index(hvac_mode)
        except ValueError as exc:
            raise ValueError(f"Unsupported HVAC mode {hvac_mode}") from exc

        mode_value = list(HVAC_MODE_MAP.keys())[mode_value_index]

        await self.coordinator.client.update_mode(mode_value)

        await self.coordinator.client.read_control()

    @override
    async def async_set_preset_mode(self, preset_mode: str) -> None:
        """Set the preset mode."""

        if preset_mode == PRESET_AWAY:
            await self.coordinator.client.set_hold(3)
        elif preset_mode == PRESET_VACATION:
            await self.coordinator.client.set_hold(4)
        elif preset_mode == PRESET_NONE:
            await self.coordinator.client.set_hold(0)
        else:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Read the entity's supported modes (entity attribute hvac_modes) and use one of those in set_hvac_mode calls.
2. Fix the automation/script to use a mode the Aprilaire thermostat supports (off/heat/cool/heat_cool per HVAC_MODE_MAP).
3. Add a Choose/condition so unsupported modes requested by generic blueprints are skipped for Aprilaire entities.

Example fix

# before
action:
  - action: climate.set_hvac_mode
    target:
      entity_id: climate.aprilaire
    data:
      hvac_mode: "dry"

# after
action:
  - action: climate.set_hvac_mode
    target:
      entity_id: climate.aprilaire
    data:
      hvac_mode: "cool"

supported = state.attributes.get("hvac_modes", [])
if hvac_mode not in supported:
    _LOGGER.warning("%s does not support hvac_mode %s", entity_id, hvac_mode)
    return

from homeassistant.components.climate import HVACMode

def is_supported_hvac_mode(mode: HVACMode | str) -> bool:
    return mode in set(HVAC_MODE_MAP.values())  # aprilaire's local map

try:
    await climate_entity.async_set_hvac_mode(hvac_mode)
except ValueError:
    # fall back to a known-supported mode or notify
raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Unsupported fan mode {fan_mode}
• Unsupported preset mode {preset_mode}
• Failed to set temperature to {temperature}.
• failed_to_read_hvac_mode
• failed_to_parse_hvac_mode

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