If one of your ESPHome nodes uses the devices: list under esphome:, the next release will refuse to compile it until you add one line per sub-device. Pull request #21232, merged into ESPHome's development branch on 22 October 2026, adds a required relation: key to every entry in that list. The change is marked as breaking and is heading for ESPHome 2026.11.

What the new key means

Sub-devices let one ESP board show up in Home Assistant as several devices, each with its own entities and area. Until now ESPHome had only one way to describe them, and Home Assistant registered each one as a separate device reached through the main node. The new key makes the node say which of two cases applies:

  • via: a separate physical device reached through this node, for example an RF sensor behind a 433 MHz bridge, or something connected over UART, ESP-NOW or UDP. This is how Home Assistant has always treated sub-devices.
  • child: a logical part of the node itself, for example one zone of a multi-zone controller.

What you have to change

The key has no default in YAML, so a config with esphome: devices: fails validation until every sub-device sets it. To keep today's behaviour, add relation: via:

esphome:
  devices:
    - id: front_door_device
      name: Front Door Sensor
      relation: via

A multi-zone controller would use relation: child for each zone instead. The documentation for the option was merged into esphome.io alongside the code.

What happens on the Home Assistant side

The value travels to Home Assistant as a new field in the device information that the native API sends. On the wire it defaults to via, so new clients read older firmware as via and older clients simply skip the field. ESPHome does not bump the API version for this. The matching change in aioesphomeapi, the library Home Assistant uses to talk to ESPHome, was merged on 21 October.

The part that makes child actually behave differently is still an open pull request in Home Assistant Core (#186150). It would register child devices as children of the main ESPHome device instead of linking them with via_device. Its own breaking change note says that targeting the main device in an automation, script or action would then also reach the entities of its child devices, and that child devices without an area would follow the main device's area. Existing sub-devices would be converted in place and keep their device IDs. Until that pull request lands, picking child mainly prepares the config.

RAM cost is small. When all sub-devices on a node share one relation, ESPHome stores nothing extra. Only a node that mixes via and child compiles in a per-device field, which takes 4 bytes per device because of padding.