home-assistant/core · warning · ValueError

Unsupported fan mode {fan_mode}

Error message

Unsupported fan mode {fan_mode}

What it means

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.

Source

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

        await self.coordinator.client.update_setpoint(cool_setpoint, heat_setpoint)

        await self.coordinator.client.read_control()

    @override
    async def async_set_humidity(self, humidity: int) -> None:
        """Set the target humidification setpoint."""

        await self.coordinator.client.set_humidification_setpoint(humidity)

    @override
    async def async_set_fan_mode(self, fan_mode: str) -> None:
        """Set the fan mode."""

        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]

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Use only 'on', 'auto', or 'circulate' in climate.set_fan_mode calls to Aprilaire entities.
2. Update the automation/script/scene to map generic fan modes to one of the three supported values before calling the service.
3. Check that you targeted the right entity_id — other climate entities in the home may accept different modes.

Example fix

# before
action:
  - action: climate.set_fan_mode
    target:
      entity_id: climate.aprilaire
    data:
      fan_mode: "low"

# after
action:
  - action: climate.set_fan_mode
    target:
      entity_id: climate.aprilaire
    data:
      fan_mode: "circulate"

SUPPORTED_FAN_MODES = {"on", "auto", "circulate"}
if fan_mode not in SUPPORTED_FAN_MODES:
    _LOGGER.warning("Skipping unsupported fan mode %s", fan_mode)
    return

def is_aprilaire_fan_mode(mode: str) -> bool:
    return mode in {"on", "auto", "circulate"}

try:
    await climate_entity.async_set_fan_mode(fan_mode)
except ValueError:
    # mode not in FAN_MODE_MAP; clamp to 'auto' or surface to user
raise

When it happens

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

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

Related errors

• Unsupported HVAC mode {hvac_mode}
• Unsupported preset mode {preset_mode}
• Failed to set temperature to {temperature}.
• failed_to_set_fan_mode
• Failed to set preset mode to {preset_mode}.

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