[Bug]: using packages key can/will leave valid config files marked as errant by code analysis

[axa88]

No evidence to suggest this bug is either invalid as a duplicate of #105.
Linking to an already closed bug with no solution other than "i dont know, it works for me" is less than a solution.

Operating System

Windows

ESPHome VSCode Extension Version

2025.7.0

ESPHome Backend

Local ESPHome

ESPHome Version

2025.7.5

What happened?

It appears having a "main" yaml that contains the esphome key, then including additional yaml files using packages key, will issue an error in the code analysis, asking to include the esphome key in the additional yaml.

'esphome' section missing from configuration. Please make sure your configuration has an 'esphome:' line in it.

But if you do so, it will be a compilation error.

Its of course expected that the code is not marked in error.

packages:
  fan_light: !include LivingFanLight.yaml

esphome:
  name: living-rf-bridge
  friendly_name: Living RF Bridge

Then any code in the LivingFanLight.yaml will trigger the errant analysis in package file

Relevant logs or output

Relevant logs or output

[glmnet]

Attach logs of esphome extension shown in vscode editor. There is a explanation in the issue template

[axa88]

Attach logs of esphome extension shown in vscode editor. There is a explanation in the issue template

How does one access these logs?
Navigating to the VSC Extension interface , i didnt notice a log output.
Surely im looking in the wrong place

[glmnet]

[axa88]

I wonder why the logs are being cut off at 156 characters...

Configuring ESPHome with local validation...
Using local ESPHome
Using Version: 2025.8.2

rcvd {"type":"version","value":"2025.8.2"}
Validating file:///c%3A/Git/HomeAssistant/EspHome/Shared/Base.yaml
send {"type":"validate","file":"c:\\Git\\HomeAssistant\\EspHome\\Shared\\Base.yaml"}
rcvd {"type":"read_file","path":"c:\\Git\\HomeAssistant\\EspHome\\Shared\\Base.yaml"}
send {"type":"file_response","content":"web_server:\r\n  port: 80\r\n  local: true\r\n  include_internal: true\r\n\r\nbinary_sensor:\r\n  - platform: statu
rcvd {"type":"result","yaml_errors":[],"validation_errors":[{"range":null,"message":"'esphome' section missing from configuration. Please make sure your co
Downloading https://schema.esphome.io/2025.8.2/schema.zip to C:\Users\axa88\.esphome-language-server\2025.8.2.zip
Downloading https://schema.esphome.io/dev/schema.zip to C:\Users\axa88\.esphome-language-server\dev.zip

The PROBLEMS tab appears to list the entire error:

[{ "resource": "/c:/Git/HomeAssistant/EspHome/Shared/Base.yaml", "owner": "_generated_diagnostic_collection_name_#0", "severity": 8, "message": "'esphome' section missing from configuration. Please make sure your configuration has an 'esphome:' line in it.", "startLineNumber": 2, "startColumn": 1, "endLineNumber": 2, "endColumn": 3, "origin": "extHost1" }]

[glmnet]

you need to include the logs generated when you open the file taht reads the Base.yaml file also

[jb1228]

Is it possible to add a setting to simply disable the 'esphome' section missing error altogether?

When using packages, includes, substitutions, sub-directories, etc. to create modular configurations, it ends up being a constant "error that cries wolf", as I am never editing files that actually need an esphome: section.

Otherwise, I like the extension. It is very helpful. Thank you!

[glmnet]

Cannot disable the error:

the error is generated by esphome because it is given a file which is not a full config and esphome properly explains the esphome section is missing.

When the extension finds a file that includes this file it realizes and then if it needs to validate the included file it will pick any file that uses this file and validate that file, hence the esphome will validate the included file.

This is still quite hacky because included files might be valid for a "parent" but not for another main file.

May be best solution would be to scan the whole folder for files that include this file and then skip validation at all or may be add a
# no validate or something in the top

Anyway understanding the "issue" is crucial to try to come up with a solution.

[jb1228]

Thanks for the explanation. I agree that trying to validate an included file by “picking any parent that references it” is inherently brittle:

• An include can be valid under one parent and invalid under another (different substitutions, templates, etc.).
• From the child file there’s no reliable, performant way to know which parent the user intends.
• Using an arbitrary parent to validate a fragment will no doubt generate false positives and confusion.

Given that, maybe a pragmatic path would be to avoid parent-based validation for fragments and let users opt out:

• Perhaps a setting could be added to suppress the root check on fragments, e.g.
  • esphome.ignoreMissingRoot (boolean, default false)
  • esphome.ignoreMissingRootGlobs (string[], default [], e.g. ["packages/**/*.yaml"])
• If a file lacks top-level esphome: and matches either condition, don’t emit the “missing esphome” diagnostic.
• When a file matches the glob list, treat it as a fragment for schema purposes so users still get completions for common sections without requiring a dummy root.

This keeps current behavior by default, avoids potentially hacky parent inference, and lets package-heavy setups silence the noisy check in a targeted way.

[neggles]

I keep hitting this issue as well and it's rather annoying since I have a few different package yamls that I'm not actually using anywhere at the moment, and the Problem stays visible in the vscode UI problems tray even after the file is closed. (as an aside, it would be nice to have the option to clear/hide problems after a file is closed, similar to what the Python extension lets you do. I'm not sure why that's not a global option in vscode, tbh.)

If I may make a suggestion, I can think of two ways to handle this that make sense:

1. Check for the presence of a first-line comment containing esphome-type: package or something along those lines, and if it's present just disable the "no root key found" problem report and otherwise continue doing what you're already doing
2. check for the presence of the defaults: top level key, since most packages will have those (all of mine do, mostly just to document what the substitutions i've used are), it's not permitted in the root of a proper config file, and adding an an empty defaults: {} to a package would work as a way to flag it as being a package rather than a config.

I suppose option 3 would be to just use presence or absence of the esphome: root key to determine whether a given file is a package or a device config, since I don't think it's super likely for people to write configs without that key, but it's probably better to require an explicit "this is a package" indicator rather than assuming people won't forget the esphome: key.

[glmnet]

The way I use esphome this solution is smart enough to be good imho, I don't deal with the missing section error in a way that annoys me and I know that if I need validation (and it is useful validation) on a included file I need to just go open the file I am most interested in and validation will work reliably.

You come with ideas but have not sent any logs or files.

So create the samples, send them, and I may agree on what can be done

[neggles]

alright maybe I was a bit too verbose with that message and came off like I'm writing with an LLM or some shit (for the record, i'm not, I just like to be clear). and I thought we'd moved on from "is this worth fixing" to "how should we fix this" but I guess not?

anyway fine here's my use case:

I have a bunch of files containing color definitions, because otherwise esphome makes it a PITA to define reusable colours for RGB LEDs.¹ they're set up as fragments i can inject using the yaml insertion operator as suggested in the esphome docs. not all of them are referenced, because they're generated by a script, so I get this, which is really annoying:

because once the extension sets that problem flag, it can only be cleared by either having the file be referenced by a valid full config, or restarting the extension host / reloading the window.

this is an extreme example but i get the same thing just from package templates I'm not using right now:

if it went away when closing the file (as with many other extensions), that'd be fine. if i could otherwise tell it "this file is a package, dont worry about it", that'd be fine too. but as-is it's really annoying, and i would really appreciate a way to solve the problem.

here's a repo with my config directory (minus secrets of course) and here's the log from the LSP parsing it all (which i had to manually strip a bunch of secrets out of) - if there are other logs you'd like i'm happy to get them.

Footnotes

1. there's a color entity but it only works with displays, not lights. for. some reason. ↩