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?

1 Like
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
5 Likes
5

Yeah, the error is confusing and very poorly written. Probably someone wrote in in 1 minute and nobody revisited it. It should be more clear about what to remove and what to put instead

6

It’s actually perfectly logical if you know YAML.

7

I have had that experience MANY times. The error (in many things) seems incomprehensible. I search the Internet for the error message and usually find something that helps. Typically, once I actually understand the issue, the error message makes perfect sense. It wasn’t helpful but makes sense.

I have nothing to do with this error message, but it seems reasonably clear to me about what is wrong. It does assume you understand basic YAML structure/terms. It does even include the offending lines that need to be removed. A simple error message can’t really tell you exactly how to fix the issue, but it could possibly include a link to the documentation.

What is the exact error message you would have liked to see that would not have caused the confusion?

8

Just like you said, a link to the documentation would have been a better alternative.
To make it perfect what it’s should say is what to use instead, and also the link.
I know YAML, and I perfectly understood the error. What it doesn’t tell you is what you should be doing. Basically it gives you a clue to get into another problem, while it could give you a solution.
I know this is general not an errors concern, but the UI could catch the error and show something more user friendly

9

The code that does this is open source. If you feel strongly about this, file an issue on GitHub and better yet a PR with the fix.

line 270 in config.py is where the message is defined

This is the commit that made it what it is today: