When an ESPHome configuration doesn't behave as expected, finding the issue tracker is often the easy part. The harder part is describing what's happening clearly enough to know where to take it. Is documented behavior broken? Is a capability missing, or is the requirement still unclear? Could a detail in the configuration, hardware, or network explain the result?
The distinction matters. An issue is easier to investigate when it describes a fault someone else can reproduce. A feature request needs a clear use case and a realistic scope. ESPHome’s contributor information directs people to GitHub issues and the organization’s discussions for feature requests. Its current getting-started guide covers the normal installation and configuration steps to work through before reporting a problem. ESPHome contributing information ESPHome getting started
This guide offers a short decision process for an installation you own or administer. Individual projects still decide how to triage reports, and maintainers may relabel, close, or redirect yours. The aim is to give them evidence that makes that decision easier.
An observable result
Start with what happened, then choose a category. Write one sentence that separates what you expected from what you saw:
With this configuration and this device, I expected X. Instead, after Y, I observed Z.
For example, “The documented mac_address setting is accepted, but after a reboot the Ethernet interface reports a different address” is testable. “MAC addresses are confusing” is important feedback, but it doesn't yet describe a fault or a change a maintainer can reproduce.
Record the exact component, platform, ESPHome version, and hardware or board, along with the Home Assistant version if it's relevant. For network behavior, the router, switch, access point, DHCP server, or device’s factory-programmed address may also affect the result. What happens on one board doesn't necessarily apply to every board in that family.
If documentation is the basis for your expectation, link the exact page and describe the behavior in your own words. If an older configuration used to work, record the last known working version and the first version where the behavior changed. A regression report is different from a request for new behavior.
The defect test
A bug report is usually the right place to start when all of these are true:
- The project documents or already implements the behavior you need.
- A supported configuration can show that the actual result differs from that behavior.
- Someone else could repeat the test with the same essential inputs.
You don't have to prove the root cause. Just don't claim to know it without evidence. A configuration that fails validation may be a defect, as may generated firmware that doesn't follow documented settings. So may a recent change that breaks a supported setup that previously worked.
Before filing, strip the configuration down. Copy the file and remove unrelated sensors and automations, leaving only the platform, network component, and setting needed to show the problem. Never publish Wi-Fi passwords, API keys, broker credentials, public IP addresses, or a complete inventory of your home network. Use clear placeholders for those values and say what you redacted.
ESPHome has commands and Device Builder actions for validating configurations and viewing logs. Its documentation says cleaning build files is safe and can resolve compile errors. Record whether you tried that before reporting a build result as a defect. ESPHome getting started
Feature requests
A feature request is a better fit when the current behavior matches the documentation, but there's no supported way to do what you legitimately need. It can also be appropriate when a setting works as intended but needs a new mode, input, or integration point.
Describe the user problem before proposing how to solve it. “Commissioning a group of similar devices requires a per-device network identity” is a problem statement. “Add a lambda to this YAML key” is one possible solution. Keeping those separate gives maintainers room to point you to an existing approach or explain a constraint. It also lets them choose an implementation that doesn't create a special case for one board.
Explain the scale and the trade-off. Is this for one experimental device, a repeatable workshop build, or a fleet? Must it work before the first network connection? Does it interact with locally administered MAC addresses, DHCP reservations, mDNS names, OTA updates, or hardware-programmed addresses? A short, concrete scenario tells maintainers more than a general statement that the feature would be convenient.
ESPHome’s current contributor file explicitly distinguishes Issues from Feature requests and links feature requests to the project’s GitHub Discussions area. GitHub describes Discussions as a place for questions, information sharing, and conversation. That makes it a suitable place to work through a requirement that's still unclear, rather than report a specific defect you can reproduce. ESPHome contributor information GitHub: About discussions
Questions about unclear behavior
Sometimes neither label fits yet. A term may have several meanings, two pages may seem to contradict each other, or a valid configuration may leave the order of operations unclear. Start with a specific question in the project’s documented community venue or discussion area. Include the smallest configuration and the actual log excerpt, and ask what behavior is supported.
When your expectation isn't documented, avoid treating a bug report as a support ticket. The question still matters. But the useful first step may be to clarify the behavior, improve the documentation, or confirm a limitation. Once you know that documented behavior fails or a capability is missing, it's easier to choose where to take the report.
Search for an existing issue or discussion first. Use the component name, board or chip family, error message, and key configuration option. Only add details to an existing report if they reproduce the same behavior. Similar symptoms can have different causes, especially with Wi-Fi, Ethernet, DHCP, and boot timing.
A small, safe evidence bundle
For either an issue or a feature request, prepare the same compact record:
- ESPHome version and installation method.
- Board or hardware identifier and the relevant network interface.
- A minimal, redacted YAML configuration.
- The exact validation result or log excerpt, including timestamps when ordering matters.
- Steps from a fresh boot or clean build to the observed result.
- Expected result, actual result, and what you've already tried.
For questions about network identity, specify which address you mean: a factory address, one configured by firmware, a locally administered address, or one shown by a router after DHCP. These aren't automatically interchangeable. A router’s client label or an mDNS hostname doesn't prove which address the firmware used at boot.
Keep tests reversible. When changing network identity, use a spare device or test during a maintenance window. An address collision can disrupt connectivity for devices beyond the one you're testing. If you change DHCP reservations or access controls for a test, say so in the report. That helps someone else understand the environment without exposing your whole network.
One clear next action
Before submitting, check which description fits:
- Documented or previously working behavior fails with a minimal reproduction: open a bug report in the project’s issue tracker.
- No documented supported path exists for a clearly described need: start a feature request through the route the project currently specifies.
- You can't yet state the expected behavior or reproduce what you observed: ask a focused question and collect more evidence first.
File one report for each underlying problem. Link related evidence instead of opening parallel reports in several places. Be ready to test a maintainer’s suggested change, but don't promise hardware access or turnaround times you can't provide.
A report with a clear scope doesn't guarantee a fix or a feature. It gives the project a starting point for reproducing a defect, assessing a request, or documenting a limitation. That's more useful than a long thread that mixes what you wanted, what happened, and how you think it should be implemented.