OTA Requires A Platform Key But It Was Not Specified | Fix

You update ESPHome, hit compile, and the run stops dead. No upload. No useful clue beyond a single line that looks like it came out of nowhere.

Most of the time, nothing is “wrong” with your device. Your YAML just doesn’t match the newer OTA format that ESPHome expects.

This article shows the exact edit that clears the error, plus the small YAML slips that make people chase their tail for an hour.

Why This Error Shows Up After An ESPHome Update

ESPHome’s OTA feature can be wired up in more than one way. Over time, the project has added more triggers, safer recovery behavior, and extra upload paths. To keep things consistent, OTA moved to the same shape used by many other components: a list of entries, each entry naming a platform.

Older configs often used a single mapping under ota:. That used to work because there was only one obvious OTA implementation for most users.

Newer releases want you to be explicit. When ESPHome reads ota: with no platform entry, it can’t pick the right code path, so it throws the message and stops the build. The current docs show the default OTA entry as platform: esphome inside a list item. ESPHome OTA docs

If you saw the error right after a version bump, that timing lines up with this format change. You didn’t break anything. Your config just needs a small refresh.

OTA Requires A Platform Key But It Was Not Specified On ESPHome

This is the fix that solves the error for most setups that do OTA through the ESPHome dashboard or the CLI.

1. Open The Device YAML — Edit the exact file that failed to compile, not a screenshot or an old backup.
2. Find The ota Block — Search for ota:. It’s often near api: and wifi:.
3. Turn ota Into A List — Add a dash and a platform line under it.
4. Keep Options Under The Same Item — Indent password and other fields under that dash.
5. Compile First — Build once before you try to upload, so YAML errors are easy to spot.

Here’s the known-good pattern from the docs, with a typical secret for the password:

ota:
  - platform: esphome
    password: !secret ota_password

If you don’t use an OTA password, you can leave the password line out. Many people still keep one because it blocks random uploads on the same network. ESPHome’s security guidance pushes strong, distinct passwords for OTA. ESPHome security guide

After this edit, the line “ota requires a platform key but it was not specified” should disappear on the next compile.

YAML Traps That Make The Fix Look Like It Didn’t Work

If you added the platform line and still get the same message, the cause is almost always YAML shape or indentation. ESPHome isn’t guessing. It reads structure.

Missing Dash Under ota

OTA is now a list. Without the dash, your platform line may be treated as a plain field under a mapping that ESPHome no longer accepts.

• Use A List Item — Put - platform: esphome on its own line under ota:.
• Keep It Aligned — The dash should be indented exactly two spaces under ota: in most common styles.

Password Not Indented Under The List Item

YAML whitespace is not cosmetic. If your password line is aligned under ota: instead of under the dashed item, you created two separate structures. ESPHome still won’t see a platform entry tied to the OTA options.

• Indent Under The Dash — Make sure password lines up under platform.
• Use Spaces Only — Tabs can look fine in an editor and still break parsing.

Two ota Blocks Merged By Packages

Packages are great until two of them define ota: in different ways. One file may keep the old mapping style, another may use the list style, and the merge can land you in an invalid middle shape.

1. Search All Files — Check your device YAML and every included package for ota:.
2. Delete The Duplicate — Keep one OTA definition and remove the others.
3. Recompile Each Time — A single build after each edit makes the failure source obvious.

Platform Added To The Wrong Block

Sometimes people paste platform under wifi: or under a sensor because another component uses a platform field too. For this error, the platform entry must sit inside the ota: list item. If it’s elsewhere, ESPHome still complains and you feel like nothing changed.

Once you fix the YAML shape, the error should stop showing. If it doesn’t, copy the known-good OTA block from the docs into your file, then re-add your password and any other options line by line.

Which Platform Entry To Use And How To Extend It Safely

For most devices, platform: esphome is the right choice because it matches the built-in OTA flow used by the dashboard and the CLI. That is the default shown in the current documentation. ESPHome OTA docs

Some setups add other OTA paths, like HTTP-triggered updates, and those bring extra OTA components with their own platform names. When you use more than one OTA method, you’ll end up with multiple items under ota:, one per method.

Situation	What You Put Under ota	What To Watch
Default OTA via dashboard or CLI	- platform: esphome	Works with the normal upload flow in the docs.
Old YAML copied from a tutorial	- platform: esphome plus your old options	Most old examples fail only because the platform line is missing.
Device built from a shared package	Define ota once, then reuse	Avoid two ota definitions merging.
Extra OTA actions and triggers	Add fields under the same item	Keep triggers under the ota entry they belong to.

If you’re not sure what you need, start with the default entry, get a clean compile, then add extra pieces one at a time. That keeps blame obvious when something breaks.

Dial In The Settings You Actually Use

Once the platform line is in place, you might notice other OTA options in examples online. You do not need to add any of them to clear the platform-entry error. Still, a few settings are worth knowing because they explain odd behavior during uploads.

• Set The Protocol Version — The OTA docs list a version option and note that version 2 is the default. If you have an older device build that only accepts version 1, you may need a staged update that switches versions in the right order.
• Pick A Port Only When Needed — ESPHome picks a default port based on the chip family. If a firewall rule or a network quirk blocks that port, setting port in the OTA entry can get uploads flowing again.
• Use An id For Advanced Password Changes — If you need to change an OTA password on a live device without losing access, the docs show a pattern that sets an id on the OTA entry and updates the password during boot code. That trick is handy when you can still upload with the old password but want to rotate it.

Safe Mode And Why It Matters

OTA can fail in ways that look scary: the device reboots mid-upload, it comes back with a fallback build, or it stops responding for a minute. ESPHome includes a safe mode path that can recover a device that keeps crashing right after boot. Safe mode is tied to the OTA component, so keeping the OTA block valid is part of staying recoverable.

If you see repeated reboots during an upload, do two things. First, reduce risk by making the next change small. Second, check logs for a crash that started right after a new sensor, a new display driver, or a big lambda. OTA itself is rarely the root cause in those cases. It’s just the delivery truck.

When You Use Packages, Make ota A Single Source Of Truth

Packages let you share a base config across devices. They also make it easy to define ota: twice by accident. If one package still has the old mapping-style OTA block and another uses the list-style block, the merged result can be invalid in a way that’s hard to spot at a glance.

1. Search For Every ota Line — Scan your main YAML and every imported package for ota:.
2. Keep One Block Only — Place the OTA list in one file and delete the rest.
3. Prefer The Base Package — Put the shared OTA block in the common package so every device inherits the same working shape.
4. Rebuild After Each Removal — A quick compile after each edit makes the last change the likely cause if a new error appears.

If you’re building on the CLI, it’s also worth knowing that some errors show before compilation truly starts. A YAML parse stop will block the rest of the run, so fixing structure early saves a ton of time.

Checks To Run Before Your Next OTA Upload

Once the YAML parses, you still want a smooth upload. A few quick checks prevent a frustrating “compile works, upload fails” loop.

1. Run A Config Check — Use esphome config yourfile.yaml to validate structure before a full build.
2. Confirm The Device Is Online — Make sure the IP hasn’t changed and the device is on the same network.
3. Verify The Secret Name — If you use !secret ota_password, confirm the name exists in your secrets file.
4. Mind The First Boot After Serial Flash — Some boards need a reset after a USB upload before OTA works again. The docs call this out for ESP8266 modules. ESPHome OTA docs
5. Keep A Serial Plan — For the first upload after big changes, having USB access saves you from a bad night.

If you still see “ota requires a platform key but it was not specified” at this point, go back to the ota block and copy the doc example fresh. Most failed fixes come down to a missing dash or a password line that isn’t indented under the list item.

What To Do After The Error Is Gone

Once your device compiles and uploads again, take a moment to make the next upgrade painless. You can do it in a few small habits that cost almost no time.

• Save A Known-Good ota Snippet — Keep the working block in a note so you can compare fast after updates.
• Update One Device First — Try new ESPHome releases on a non-critical device before touching the rest.
• Review The Changelog When You Upgrade — Format shifts are usually called out, and they often include the new YAML shape.
• Keep Secrets Consistent — Use the same secret name labels across devices to avoid typo hunts.
• Document Packages Clearly — When a package defines ota, note it near the import line so you don’t define ota twice later.

If you manage many devices, this is also a good moment to standardize a shared ota block with - platform: esphome and reuse it across your fleet. That way, one update fixes the pattern everywhere.

One last thing that saves time is pinning your ESPHome version for a week after a clean upgrade. If you run a batch update and a new release lands the next day, you may chase two changes at once. Update the core, compile once, then leave it alone while you watch devices for a day or two. When every node stays stable, you can update again with less stress. Keep a copy of the working firmware bin for quick reflash in a pinch.