home-assistant/core · error · HomeAssistantError

failed_to_parse_hvac_mode

failed_to_parse_hvac_mode

Error message

Cannot parse response to HVACMode: {mode}

What it means

HomeAssistantError with translation_key 'failed_to_parse_hvac_mode' (placeholder: mode), raised when read_hvac_mode() did return data but the mode string is not one of HEAT/COOL/AUTO/OFF after upper-casing. The gateway reported a mode the mapping dict does not know, so the raw mode is included for diagnosis.

Source

Thrown at homeassistant/components/bryant_evolution/climate.py:160

        # Note: depends on current temperature and target temperature low read
        # above.
        self._attr_hvac_action = await self._read_hvac_action()

    async def _read_hvac_mode(self) -> HVACMode:
        mode_and_active = await self._client.read_hvac_mode()
        if not mode_and_active:
            raise HomeAssistantError(
                translation_domain=DOMAIN, translation_key="failed_to_read_hvac_mode"
            )
        mode = mode_and_active[0]
        mode_enum = {
            "HEAT": HVACMode.HEAT,
            "COOL": HVACMode.COOL,
            "AUTO": HVACMode.HEAT_COOL,
            "OFF": HVACMode.OFF,
        }.get(mode.upper())
        if mode_enum is None:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="failed_to_parse_hvac_mode",
                translation_placeholders={"mode": mode},
            )
        return mode_enum

    async def _read_hvac_action(self) -> HVACAction:
        """Return the current running hvac operation."""
        mode_and_active = await self._client.read_hvac_mode()
        if not mode_and_active:
            raise HomeAssistantError(
                translation_domain=DOMAIN, translation_key="failed_to_read_hvac_action"
            )
        mode, is_active = mode_and_active
        if not is_active:
            return HVACAction.OFF
        match mode.upper():
            case "HEAT":

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check the logged placeholder value — the unrecognized mode string identifies the gap
2. Update the bryant_evolution integration / evolutionhttp library for extended mode support
3. Report the unknown mode string upstream with your system model/firmware
4. As a workaround, use the thermostat's physical controls for the unsupported mode

Example fix

# conceptually, in the mapping (integration code, upstream fix)
# before
mode_enum = {'HEAT': HVACMode.HEAT, 'COOL': HVACMode.COOL,
              'AUTO': HVACMode.HEAT_COOL, 'OFF': HVACMode.OFF}.get(mode.upper())

# after (once upstream adds the mode)
mode_enum = {'HEAT': HVACMode.HEAT, 'COOL': HVACMode.COOL,
              'AUTO': HVACMode.HEAT_COOL, 'OFF': HVACMode.OFF,
              'EMERGENCY HEAT': HVACMode.HEAT}.get(mode.upper())

mode_and_active = await client.read_hvac_mode()
mode = mode_and_active[0] if mode_and_active else None
mode_supported = mode is not None and mode.upper() in {'HEAT', 'COOL', 'AUTO', 'OFF'}
if not mode_supported:
    # avoid the parse error; surface the raw mode instead

from homeassistant.components.climate import HVACMode

SUPPORTED_MODES = {'HEAT', 'COOL', 'AUTO', 'OFF'}

def is_supported_hvac_mode(mode_and_active: tuple[str, bool] | None) -> bool:
    """True when the gateway mode maps to an HVACMode."""
    if not mode_and_active:
        return False
    return mode_and_active[0].upper() in SUPPORTED_MODES

When it happens

Trigger: Gateway firmware exposing additional or renamed modes (e.g. a proprietary 'EMERGENCY HEAT' string) not covered by the four-entry map; localized or malformed responses from a non-standard system configuration.

Common situations: Newer Evolution firmware adding modes; systems with accessories (humidifier/dehumidifier modes) leaking into the mode register; library lag behind firmware.

Related errors

• failed_to_read_hvac_mode
• failed_to_set_hvac_mode
• Unsupported HVAC mode {hvac_mode}
• failed_to_read_hvac_action
• failed_to_parse_hvac_action

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