Version: 2025.12.7 broke all of my projects. (Sort of)

ESPHome
1

Problem- I have not been using packages correctly?

Since 99% of my ESPHome projects use the Wemods D1 Mini development board, I put all of the yaml parts that were common to every board into a package:
Example:

substitutions:
  device_name: blink
  friendly_name: blink
  project_version: "1.0"
packages:
  device_base: !include common/d1_mini.yaml

Below that simple header is the yaml unique to this project.
This made my project files very clean. Those seven lines replaced 40 lines that were identical in every one of my projects.

What broke?
I had used packages like a substitution.
Now, packages may not be the only source of blocks, like esphome:
Before 2025.12.7 I could use the package as an include file.

Since there is no “include” in ESPHome, am I stuck with expanding my package content into the main project file?

2

Is that local package?

Get rid of “device base” you only need “include” as a list according to docs

3

UPDATE, fixed the platform error but a new one shows up. Next post

Thanks for the tip, but it’s still not working for me.

substitutions:
  device_name: server-fan-controller
  friendly_name: Server Fan Controller
  project_version: "1.0"
  my_ssid: !secret iot_ssid
  my_pass: !secret iot_password

packages:
  - !include common/wemos.yaml

And wemos.yaml:

# ==========================================================
# Wemos Base Package
# Shared configuration for ESP8266 devices
# 
# Useage
# substitutions:
#  device_name: server-fan-controller
#  friendly_name: Server Fan Controller
#  project_version: "1.0"
#  my_ssid: !secret iot_ssid
#  my_pass: !secret iot_password
# packages:
#   !include common/wemos.yaml
#
# ==========================================================

esphome:
  name: ${device_name}
  friendly_name: ${friendly_name}
  project:
    name: ${device_name}
    version: ${project_version}

# Enable API for Home Assistant
# Disable the watchdog timeout
api:
  reboot_timeout: 0s

# Logging
logger:
  level: DEBUG

# WiFi configuration
wifi:
  ssid: ${my_ssid}
  password: ${my_pass}
  power_save_mode: none

# mDNS
mdns:
  disabled: false

# WiFi security
# min_auth_mode:
#   WPA2

# OTA updates
ota:
  platform: esphome

# Web server
web_server:
  port: 80

# ==========================================================
# End of package
# ==========================================================

This gives the following compile error:

esphome: [source /config/esphome/common/wemos.yaml:18]
  
  Platform missing. You must include one of the available platform keys: bk72xx, esp8266, esp32, ln882x, nrf52, libretiny, rp2040, rtl87xx, host.
  name: server-fan-controller
  friendly_name: Server Fan Controller
  project: 
    name: server-fan-controller
    version: 1.0

If I include platform, I get another error that says to remove platform?

esphome: [source /config/esphome/common/wemos.yaml:18]
  name: server-fan-controller
  friendly_name: Server Fan Controller
  
  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
  project: 
    name: server-fan-controller
    version: 1.0

Am I putting the key in the wrong place?

4

What version of esphome were you running before 2025.12.7?

The change affecting you was rolled out about 11 months ago.

See the following to sources for references:

And I think for your example you’d want to change the top of your common yaml file to (something like):

esphome:
  name: ${device_name}
  friendly_name: ${friendly_name}
  project:
    name: ${device_name}
    version: ${project_version}

esp8266:
  board: d1_mini

# Enable API for Home Assistant
# Disable the watchdog timeout
...
5

Never mind. Your tip fixed the issue and thanks for the link to the docs. Somehow, I missed the change notes covering this.

Also, I was chasing the red-lined errors in the project yaml file and stumbled on the answer that the platform MUST be defined in the project file:

substitutions:
  device_name: server-fan-controller
  friendly_name: Server Fan Controller
  project_version: "1.0"
  my_ssid: !secret iot_ssid
  my_pass: !secret iot_password

packages:
  - !include common/wemos.yaml

esphome:
  name: ${device_name}

name: cannot be only in the include file. If it is, the binary will compile and run OK, but there will be red-lined errors on the editor.

Thanks again for pointing me in the right direction.

6

No worries! I’ve been out of touch myself with esphome updates and the top-level platform components also bit me very recently!

7

I have the firmware entity turned off on all but two of my devices. These two are on my desktop and easily accessible if I need to plug in the USB to flash it again. They are my canaries in the coal mine.