Duplicate ESPHome entries commonly appear after a device name change, board replacement, restored backup, or re-adoption. One entry may use the native API while another is a stale registry record. Deleting both entries can turn a cosmetic problem into an outage, so identify which connection is live first.
What this failure pattern tells you
This guide uses a narrow diagnostic sequence: confirm the pattern, protect the current configuration, test the smallest likely cause, and verify the result before moving deeper. That approach avoids turning one failed device or automation into a site-wide recovery job.
- Two devices have similar names but different entity counts.
- One copy is unavailable while the other updates normally.
- Automations reference entities from both entries.
- A renamed node keeps its old device or entities.
Most likely causes
- The ESPHome node name or friendly name changed.
- A replacement board reused some identifiers but not the original API identity.
- An old integration entry survived a reinstall or restore.
- Entities were disabled or renamed, making the working copy difficult to recognize.
- mDNS discovery found a node that had also been added manually.
Before changing anything
Make a current Home Assistant backup and download it somewhere outside the system. Take screenshots of the affected integration, device, entity IDs, and any relevant automation. Record the exact time of the next failure so the log window stays small. If the issue involves radio hardware, do not unplug it while Home Assistant is writing data.
Step-by-step diagnosis and repair
- Open both device pages and record the integration entry, IP address, last-updated behavior, and entity IDs.
- Trigger a harmless physical change such as toggling an onboard LED or watching a sensor update; identify the entry receiving fresh state.
- Open automations, scripts, dashboards, and scenes that use the stale entity IDs and move them to the live entities before removal.
- Create a backup and export or copy the working ESPHome YAML.
- Remove only the unavailable integration entry from Settings → Devices & services. Do not delete the working node from the ESPHome dashboard.
- Restart Home Assistant once and allow discovery to settle.
- If the duplicate returns, compare the node name, API encryption key, static IP, and manual integration host. Keep one consistent discovery method.
- Rename entities for clarity only after the device registry is stable.
How to verify the repair
Do not declare success immediately after a reload. Repeat the original action several times, then observe the system through at least one normal restart or reconnect cycle. Review the log at the exact test time and confirm that the affected entities update normally. If the problem was intermittent, keep a short note of the previous failure interval and monitor beyond it.
Common mistakes to avoid
- Do not wipe the board merely to clean the registry.
- Do not delete both integrations at once.
- Do not reuse the same node name for two powered devices on the same network.
A practical decision rule
If several unrelated devices fail at the same moment, investigate shared infrastructure: power, network, broker, radio, host load, or a recent update. If only one model or entity fails while everything around it remains stable, focus on that device’s identity, firmware, configuration, and signal path. Rebuilding a healthy shared integration should be the final option, not the first.
When to restore a backup
Restore only when you can identify a known-good backup from before a harmful configuration change and you understand what newer changes will be lost. A backup is not a substitute for diagnosing failing hardware, interference, duplicate identifiers, or unstable power; those problems will return after restoration.
Frequently asked questions
Will removing the stale entry erase the ESPHome firmware?
No. Removing an integration entry from Home Assistant does not normally erase firmware from the microcontroller.
Why did the duplicate return?
The device may still advertise a different identity, or a manual host entry may coexist with automatic discovery.
What should I back up?
The ESPHome YAML, secrets references, API encryption key, and any automation entity mappings.
Bottom line
Start with evidence from the affected device, integration, trace, or topic. Protect the working system, change one variable, and verify through the original failure condition. That is slower than random resets for five minutes and much faster than rebuilding an entire smart home unnecessarily.
Deep diagnostic worksheet
Use this worksheet when the quick repair does not hold. The objective is to build a timestamped explanation of the duplicate ESPHome entry problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.
- Write down both device IDs, integration-entry names, host addresses, entity counts, and last-updated times before deleting anything. Similar display names do not prove that two records represent the same API identity.
- Trigger a harmless live change and watch which entity updates. The responding entry is the operational record; an unavailable copy may be stale, but automation references must still be migrated before removal.
- Open the ESPHome YAML and record the node name, friendly name, API encryption configuration, Wi-Fi addressing, and any name_add_mac_suffix behavior. Identity changes can produce new discovery records.
- Search Home Assistant automations, scripts, scenes, dashboards, and helpers for entity IDs belonging to both copies. A clean device list is not useful if hidden references break afterward.
- Compare manual integration configuration with automatic mDNS discovery. A manually added IP plus a separately discovered identity can look like duplication even when only one board exists.
- Confirm that two physical boards are not using the same node name or static IP. Power one board at a time if necessary and observe which record changes availability.
- If the board was replaced, decide deliberately whether the new device should inherit the old logical role. Rename and remap entities after connectivity is stable, not during discovery troubleshooting.
- Back up the YAML, secrets reference, encryption key, and automation mappings. Removing a Home Assistant integration entry normally does not erase firmware, but losing configuration still creates recovery work.
Failure-pattern examples
- Old entry unavailable, new entry healthy after a rename: migrate every reference to the new entities, verify automations, then remove only the stale integration entry.
- Two entries alternate availability: check duplicate IP addresses, duplicate node names, cloned firmware, and whether two boards share credentials or network identity.
- Duplicate returns after deletion: identify the discovery advertisement and any manual host entry. Do not keep deleting the symptom while the device continues advertising a second identity.
- Replacement board should assume the old role: preserve a clear mapping of entity IDs and update consumers methodically; do not expect identical registry identity automatically.
- mDNS is disabled or blocked: follow ESPHome guidance by using stable addressing and a deliberate manual integration rather than relying on discovery that cannot traverse the network.
Advanced notes that prevent false fixes
- The node name affects hostname and discovery, while the friendly name mainly affects presentation; changing them has different consequences.
- API encryption keys must match between firmware and Home Assistant. A mismatch is a connection problem, not evidence that the registry should be erased.
- Disabled entities can make two entries look different, so compare full entity lists rather than only dashboard cards.
- Entity IDs are user-facing references; device and config-entry identifiers are separate registry layers.
- Restoring an old Home Assistant backup while devices run newer identities can reintroduce stale registry records.
- Document the final node name, IP strategy, encryption-key storage, and entity mapping after cleanup.
Final verification checklist
Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.
- Only one intended integration entry remains.
- The live device reconnects after a normal restart.
- Every automation and dashboard uses current entity IDs.
- No duplicate IP or hostname exists on the LAN.
- Encryption works without repeated authentication errors.
- The duplicate does not return after the next discovery cycle.
Official reference
Technical behavior and terminology were checked against ESPHome Native API documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.