ESPHome 2026.9 — what changed for you

Encrypted firmware updates arrived. Three older configs will stop validating — here is what each error means and the one-line fix.

Updated 18 September 2026 esphometroubleshootingsecurity

ESPHome 2026.9 shipped encrypted OTA updates, and tightened validation on a few config shapes that used to be accepted. If a device's config suddenly fails to validate or compile after this update, it is almost always one of the three below rather than anything wrong with your hardware.

Encrypted firmware updates (new, worth turning on)

Before 2026.9, a firmware update travelled across your network in plain text — anyone on the same Wi-Fi could, in principle, read your Wi-Fi password and API key out of it as it went past. Updates can now be encrypted the same way the native API already is.

If a device already has an api: encryption key configured, add:

ota:
  - platform: esphome
    encryption:

A bare encryption: block reuses the device's existing API key — you do not need a second secret. Once a device is running 2026.9, its updates from then on are encrypted; the one that brings it to 2026.9 still goes over the network in plain text, because the old firmware does not understand the new option yet. That single crossing is unavoidable; every update after it is not.

"custom_command is deprecated" or a Modbus device that stopped validating

Modbus configs were reworked in this release. If you wrote your own modbus_controller: block (rather than using a pre-built device package), you may hit:

• custom_command: is renamed to custom_pdu:, and it now takes only the function code and data — not the full frame with device address and checksum. ESPHome adds those itself.
• skip_updates: on an individual sensor has been removed. If you were using it to poll one sensor less often than the rest, give it its own modbus_controller: with a slower update_interval: instead.
• register_count: and force_new_range: are replaced by a single reuse_previous_range: option.
• Holding-register switches and outputs: if you used offset: to reach a second byte inside a register, check the value you use hasn't changed — ESPHome now reads it directly instead of doubling it internally.

None of these fail silently: a config using the old spelling will not validate, so you will see the error before anything is flashed.

ESP8266 device: "requires Arduino framework 3.0.0 or newer"

If an ESP8266 config pins an older Arduino framework version under esp8266: framework: version:, it now fails validation outright rather than building with the old toolchain. Remove the pinned version: (ESPHome will pick a current one) or set it to 3.1.2 or later.

A device changed its MAC address after the update

This one only affects boards with a custom MAC address burned into their eFuses — uncommon, but if it applies to you it is worth knowing about before it happens rather than after. ESPHome now applies that burned-in MAC to Ethernet, Bluetooth and 802.15.4 (Thread/Zigbee) before anything else on the device starts, which changes the address those interfaces present. If you have a DHCP reservation, a firewall rule, or a Thread/Bluetooth pairing keyed to the old address, it will need updating — or add this to keep the previous behaviour:

esp32:
  advanced:
    ignore_efuse_custom_mac: true