Error: "Please remove the 'platform' key from the [esphome] block..."

ESPHome
1

After updating ESPHome, my 8266 devices are not updating. Here is the error:

INFO ESPHome 2025.3.3
INFO Reading configuration /config/esphome/garage-door.yaml...
Failed config

esphome: [source /config/esphome/garage-door.yaml:2]
  name: garage-door
  
  Please remove the `platform` key from the [esphome] block and use the correct platform component. This style of configuration has now been removed.
  platform: ESP8266
  board: d1_mini

My config file begins with:

esphome:
  name: garage-door
  platform: ESP8266
  board: d1_mini

# Enable logging
logger:

# Enable Home Assistant API
api:

ota:
  platform: esphome
  password: " "
. . .

The error is cryptic to me: What is a platform “key”? I’ve played with removing the platform line in the esphome block, but then I get a different error telling me that I’m missing the platform key.

The OTA updates doc page doesn’t seem to help. There may be an explanation of the configuration change but I’ve not found it. Can someone point me in the right direction?

2

platform: ESP8266

That is old and deprecated config. Check the documentation for the new format here: ESPHome Core Configuration — ESPHome and here: ESP8266 Platform — ESPHome

FYI in yaml the pairs around the : are called

key: value

So “platform” is the key and “ESP8266” is the value.

1 Like
3

Thanks Tom… figured it out with your help!

1 Like
4

I hit this same issue and wasn’t sure how to fix this.

I tried to remove the “platform: esp8266” as the text says, and that fails - both the web page editor shows an error and an “install” failed.

But then it said I needed a “platform” which was really confusing since it just said I had to remove it. I read the linked documentation and was rather confused.

Anyway the exact change required is to remove the “platform: value” and it’s “board: value” lines and put them in a follow on yaml section as a top-level key.

So this old out of date style:

esphome:
  name: some-name
  platform: ESP8266
  board: someboard

Becomes this using the new style:

esphome:
  name: some-name

esp8266:
  board: someboard
1 Like