Skip to content

Document ESPHome reconfig and name conflict resolution #38680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 22, 2025
Merged

Document ESPHome reconfig and name conflict resolution #38680

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a44f96
Document ESPHome reconfig and name conflict resolution
bdraco Apr 22, 2025
7a1744b
Document ESPHome reconfig and name conflict resolution
bdraco Apr 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions source/_integrations/esphome.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,3 +100,42 @@ The entity will be named `livingroomdesk Temperature` and will default to having
data:
homeassistant.components.esphome: debug
```

## Reconfiguration and Device Replacement

This integration supports reconfiguration, allowing you to make changes—such as updating the IP address—even after a device has already been set up.

### Name Conflict Resolution

If Home Assistant detects multiple devices with the same [**name**](https://esphome.io/components/esphome.html#configuration-variables), it will automatically initiate **Name Conflict Resolution**. This process is designed to help you seamlessly replace a failed or retired device with new hardware, while preserving your existing configuration if desired.

This process gives you two options:

- **Migrate**: Transfers the existing entity configuration to the new device. This preserves all your settings, entity names, and history. Use this when you're replacing the hardware but keeping the same YAML configuration.
- **Overwrite**: Replaces the existing configuration with the new device.
**Caution:** This will **erase all existing settings** for the old device including entity names, customizations, and history will be lost. Use this only if the new device is completely different and you don’t need anything from the previous setup.

{% tip %}
If you’re using the same YAML file on the new device, choose **Migrate**. If it’s a totally different device (even if it shares the same name), **Overwrite** is the safer option.
{% endtip %}

---

### Requirements for Name Conflict Resolution

To trigger Name Conflict Resolution, all of the following must be true:

- The new device must be running **ESPHome 2025.4.0 or later**.
- The new device must use the same [**name**](https://esphome.io/components/esphome.html#configuration-variables) (not just the friendly name).
- The original (old) device must be **offline**.

---

### How to Trigger Name Conflict Resolution

You can trigger Name Conflict Resolution in several ways:

- Connecting a new device with the same name and a **static IP address** will automatically launch a repair flow.
- Using the **Reconfigure** option in the UI to point to a different IP that hosts a device with the same name.
- Configuring a **newly discovered device** that uses the same name.
- **Manually adding** a device with the same name via the integration setup.