Fall back to normal "not found" when no replacement is available

When a referenced device is a removed composite device but none of its split devices are available (all deleted, or none match the picker's filters), don't surface any replaced-specific UI — just behave like a normal unknown/not-found device. - Device picker: only show the warning name and the replace alert when there is an available replacement; otherwise render the raw id and the standard "unknown device" text, with no alert. - Compact target chip: only apply the replaced (warning) treatment when a replacement device still exists. Removes the now-unused device-picker.device_replaced and device_replaced_no_match strings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Handle deleted replacement devices gracefully
2026-07-19 09:35:51 +00:00 · 2026-07-17 16:34:12 +02:00 · 2026-07-17 16:27:35 +02:00 · 2026-07-17 16:18:59 +02:00
11 changed files with 999 additions and 73 deletions
@@ -0,0 +1,23 @@
+---
+title: Replaced device selectors
+subtitle: How device and target selectors surface devices that were split into separate devices
+---
+
+A device that used to belong to multiple config entries is split into one
+device per config entry. The original composite device is removed from the
+registry, so existing references to it (targets in automations, device
+selectors) point at a device that no longer exists.
+
+When a selector holds such a reference, it shows a **replaced** state instead of
+a plain "not found", and offers to point the reference at the replacement
+device(s). The candidate replacements are filtered through the selector's own
+filters, so in practice usually a single device matches:
+
+- **Target selector** — the replaced device row offers **Replace**, which adds
+  every replacement device that matches the target filters and removes the old
+  reference.
+- **Device selector** — when exactly one replacement matches, **Replace** swaps
+  to it in one click; when several match, a dialog lets you pick one.
+
+All samples below reference the removed composite device `old_composite`, which
+was split into a light device and a switch device.
@@ -0,0 +1,314 @@
+import type { HassServiceTarget } from "home-assistant-js-websocket";
+import type { TemplateResult } from "lit";
+import { css, html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators";
+import { mockAreaRegistry } from "../../../../demo/src/stubs/area_registry";
+import { mockConfigEntries } from "../../../../demo/src/stubs/config_entries";
+import { mockDeviceRegistry } from "../../../../demo/src/stubs/device_registry";
+import { mockEntityRegistry } from "../../../../demo/src/stubs/entity_registry";
+import { mockHassioSupervisor } from "../../../../demo/src/stubs/hassio_supervisor";
+import type { HASSDomEvent } from "../../../../src/common/dom/fire_event";
+import "../../../../src/components/ha-selector/ha-selector";
+import "../../../../src/components/ha-settings-row";
+import "../../../../src/components/ha-target-picker";
+import type { AreaRegistryEntry } from "../../../../src/data/area/area_registry";
+import type { DeviceRegistryEntry } from "../../../../src/data/device/device_registry";
+import type { EntityRegistryDisplayEntry } from "../../../../src/data/entity/entity_registry";
+import type { Selector } from "../../../../src/data/selector";
+import {
+  showDialog,
+  type ShowDialogParams,
+} from "../../../../src/dialogs/make-dialog-manager";
+import { provideHass } from "../../../../src/fake_data/provide_hass";
+import type { ProvideHassElement } from "../../../../src/mixins/provide-hass-lit-mixin";
+import type { HomeAssistant } from "../../../../src/types";
+import "../../components/demo-black-white-row";
+
+// The composite device "old_composite" is intentionally NOT in the registry:
+// it was split into "device_light" and "device_switch". References to the old
+// id (targets, device selectors) should surface a "replaced" state.
+const DEVICES: DeviceRegistryEntry[] = [
+  {
+    area_id: "bedroom",
+    configuration_url: null,
+    config_entries: ["config_entry_light"],
+    config_entries_subentries: {},
+    connections: [],
+    disabled_by: null,
+    entry_type: null,
+    id: "device_light",
+    identifiers: [["demo", "light"] as [string, string]],
+    manufacturer: null,
+    model: null,
+    model_id: null,
+    name_by_user: null,
+    name: "Living room lamp",
+    sw_version: null,
+    hw_version: null,
+    via_device_id: null,
+    serial_number: null,
+    labels: [],
+    created_at: 0,
+    modified_at: 0,
+    primary_config_entry: null,
+  },
+  {
+    area_id: "backyard",
+    configuration_url: null,
+    config_entries: ["config_entry_switch"],
+    config_entries_subentries: {},
+    connections: [],
+    disabled_by: null,
+    entry_type: null,
+    id: "device_switch",
+    identifiers: [["demo", "switch"] as [string, string]],
+    manufacturer: null,
+    model: null,
+    model_id: null,
+    name_by_user: null,
+    name: "Garden socket",
+    sw_version: null,
+    hw_version: null,
+    via_device_id: null,
+    serial_number: null,
+    labels: [],
+    created_at: 0,
+    modified_at: 0,
+    primary_config_entry: null,
+  },
+];
+
+const ENTITIES = [
+  {
+    entity_id: "light.living_room_lamp",
+    state: "on",
+    attributes: { friendly_name: "Living room lamp" },
+  },
+  {
+    entity_id: "switch.garden_socket",
+    state: "off",
+    attributes: { friendly_name: "Garden socket" },
+  },
+];
+
+// Registry display entries link the demo entities to the split devices so the
+// pickers can filter split candidates by domain.
+const ENTITY_REGISTRY: Record<string, EntityRegistryDisplayEntry> = {
+  "light.living_room_lamp": {
+    entity_id: "light.living_room_lamp",
+    name: "Living room lamp",
+    device_id: "device_light",
+    area_id: "bedroom",
+    platform: "demo",
+    labels: [],
+  },
+  "switch.garden_socket": {
+    entity_id: "switch.garden_socket",
+    name: "Garden socket",
+    device_id: "device_switch",
+    area_id: "backyard",
+    platform: "demo",
+    labels: [],
+  },
+};
+
+const AREAS: AreaRegistryEntry[] = [
+  {
+    area_id: "backyard",
+    floor_id: null,
+    name: "Backyard",
+    icon: null,
+    picture: null,
+    aliases: [],
+    labels: [],
+    temperature_entity_id: null,
+    humidity_entity_id: null,
+    created_at: 0,
+    modified_at: 0,
+  },
+  {
+    area_id: "bedroom",
+    floor_id: null,
+    name: "Bedroom",
+    icon: "mdi:bed",
+    picture: null,
+    aliases: [],
+    labels: [],
+    temperature_entity_id: null,
+    humidity_entity_id: null,
+    created_at: 0,
+    modified_at: 0,
+  },
+];
+
+// Maps the removed composite device to the devices that replaced it.
+const COMPOSITE_SPLITS = {
+  old_composite: {
+    split_ids: ["device_light", "device_switch"],
+    primary_id: "device_light",
+  },
+};
+
+interface Sample {
+  name: string;
+  description: string;
+  selector: Selector;
+  value: unknown;
+  // Render ha-target-picker directly in compact (chip) mode instead of the
+  // ha-selector, which does not expose the compact option.
+  compact?: boolean;
+}
+
+const SAMPLES: Sample[] = [
+  {
+    name: "Target",
+    description:
+      "Migrate adds every replacement device that matches the target filters (here both).",
+    selector: { target: {} },
+    value: { device_id: ["old_composite"] },
+  },
+  {
+    name: "Target (compact)",
+    description:
+      "In compact mode the replaced reference is shown as a warning chip.",
+    selector: { target: {} },
+    value: { device_id: ["old_composite"] },
+    compact: true,
+  },
+  {
+    name: "Device (unfiltered, multiple matches)",
+    description:
+      "Both replacement devices qualify, so Replace opens a dialog to pick one.",
+    selector: { device: {} },
+    value: "old_composite",
+  },
+  {
+    name: "Device (filtered to lights, single match)",
+    description:
+      "Only the light device passes the filter, so Replace swaps to it in one click.",
+    selector: { device: { entity: [{ domain: "light" }] } },
+    value: "old_composite",
+  },
+  {
+    name: "Device (multiple)",
+    description: "Each slot resolves independently to a matching replacement.",
+    selector: { device: { multiple: true } },
+    value: ["old_composite"],
+  },
+];
+
+@customElement("demo-components-ha-selector-replaced-device")
+class DemoHaSelectorReplacedDevice
+  extends LitElement
+  implements ProvideHassElement
+{
+  @state() public hass!: HomeAssistant;
+
+  private _values = SAMPLES.map((sample) => sample.value);
+
+  constructor() {
+    super();
+    const hass = provideHass(this);
+    hass.updateTranslations(null, "en");
+    hass.updateTranslations("config", "en");
+    hass.addEntities(ENTITIES);
+    mockEntityRegistry(hass);
+    mockDeviceRegistry(hass, DEVICES);
+    mockConfigEntries(hass);
+    mockAreaRegistry(hass, AREAS);
+    mockHassioSupervisor(hass);
+    // Link the demo entities to the split devices.
+    hass.updateHass({ entities: ENTITY_REGISTRY });
+    hass.mockWS(
+      "config/device_registry/list_composite_splits",
+      () => COMPOSITE_SPLITS
+    );
+    hass.mockWS("extract_from_target", () => ({
+      referenced_entities: [],
+      referenced_devices: [],
+      referenced_areas: [],
+    }));
+    hass.mockWS("auth/sign_path", (params) => params);
+  }
+
+  public provideHass(el) {
+    el.hass = this.hass;
+  }
+
+  public connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener("show-dialog", this._dialogManager);
+  }
+
+  public disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListener("show-dialog", this._dialogManager);
+  }
+
+  private _dialogManager = (e: HASSDomEvent<ShowDialogParams<unknown>>) => {
+    const { dialogTag, dialogImport, dialogParams, addHistory, parentElement } =
+      e.detail;
+    showDialog(
+      this,
+      dialogTag,
+      dialogParams,
+      dialogImport,
+      parentElement,
+      addHistory
+    );
+  };
+
+  protected render(): TemplateResult {
+    return html`
+      ${SAMPLES.map(
+        (sample, idx) => html`
+          <demo-black-white-row .title=${sample.name}>
+            ${["light", "dark"].map(
+              (slot) => html`
+                <ha-settings-row narrow slot=${slot}>
+                  <span slot="heading">${sample.name}</span>
+                  <span slot="description">${sample.description}</span>
+                  ${
+                    sample.compact
+                      ? html`<ha-target-picker
+                          compact
+                          .hass=${this.hass}
+                          .value=${this._values[idx] as HassServiceTarget}
+                          .sampleIdx=${idx}
+                          @value-changed=${this._handleValueChanged}
+                        ></ha-target-picker>`
+                      : html`<ha-selector
+                          .hass=${this.hass}
+                          .selector=${sample.selector}
+                          .value=${this._values[idx]}
+                          .sampleIdx=${idx}
+                          @value-changed=${this._handleValueChanged}
+                        ></ha-selector>`
+                  }
+                </ha-settings-row>
+              `
+            )}
+          </demo-black-white-row>
+        `
+      )}
+    `;
+  }
+
+  private _handleValueChanged(ev) {
+    const idx = ev.target.sampleIdx;
+    this._values[idx] = ev.detail.value;
+    this.requestUpdate();
+  }
+
+  static styles = css`
+    ha-settings-row {
+      --settings-row-content-width: 100%;
+    }
+  `;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "demo-components-ha-selector-replaced-device": DemoHaSelectorReplacedDevice;
+  }
+}
@@ -0,0 +1,124 @@
+import { mdiDevices } from "@mdi/js";
+import { css, html, LitElement, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators";
+import { fireEvent } from "../../common/dom/fire_event";
+import { computeAreaName } from "../../common/entity/compute_area_name";
+import { computeDeviceName } from "../../common/entity/compute_device_name";
+import { getDeviceArea } from "../../common/entity/context/get_device_context";
+import type { HomeAssistant } from "../../types";
+import type { HassDialog } from "../../dialogs/make-dialog-manager";
+import "../ha-dialog";
+import "../ha-svg-icon";
+import "../item/ha-list-item-button";
+import "../list/ha-list-base";
+import type { DeviceReplacedDialogParams } from "./show-dialog-device-replaced";
+
+@customElement("dialog-device-replaced")
+export class DialogDeviceReplaced
+  extends LitElement
+  implements HassDialog<DeviceReplacedDialogParams>
+{
+  @state() private _params?: DeviceReplacedDialogParams;
+
+  @state() private _open = false;
+
+  @property({ attribute: false }) public hass!: HomeAssistant;
+
+  public async showDialog(params: DeviceReplacedDialogParams): Promise<void> {
+    this._params = params;
+    this._open = true;
+  }
+
+  public closeDialog(): boolean {
+    this._open = false;
+    return true;
+  }
+
+  private _dialogClosed(): void {
+    this._params = undefined;
+    fireEvent(this, "dialog-closed", { dialog: this.localName });
+  }
+
+  private _pick(ev: Event): void {
+    const item = (ev.target as HTMLElement).closest("ha-list-item-button") as
+      (HTMLElement & { deviceId?: string }) | null;
+    if (!item?.deviceId) {
+      return;
+    }
+    this._params?.onResolved(item.deviceId);
+    this.closeDialog();
+  }
+
+  protected render() {
+    if (!this._params || !this.hass) {
+      return nothing;
+    }
+
+    return html`
+      <ha-dialog
+        .open=${this._open}
+        .headerTitle=${this.hass.localize(
+          "ui.components.device-picker.replaced_dialog.title"
+        )}
+        @closed=${this._dialogClosed}
+      >
+        <p class="description">
+          ${this.hass.localize(
+            "ui.components.device-picker.replaced_dialog.description"
+          )}
+        </p>
+        <ha-list-base @click=${this._pick}>
+          ${this._params.candidates.map((deviceId) => {
+            const device = this.hass.devices[deviceId];
+            const name = device ? computeDeviceName(device) : deviceId;
+            const area = device
+              ? getDeviceArea(device, this.hass.areas)
+              : undefined;
+            const secondary = area ? computeAreaName(area) : undefined;
+            const isPrimary = deviceId === this._params!.primaryId;
+            return html`
+              <ha-list-item-button .deviceId=${deviceId}>
+                <ha-svg-icon slot="start" .path=${mdiDevices}></ha-svg-icon>
+                <span slot="headline">${name}</span>
+                ${
+                  secondary || isPrimary
+                    ? html`<span slot="supporting-text">
+                        ${[
+                          secondary,
+                          isPrimary
+                            ? this.hass.localize(
+                                "ui.components.device-picker.replaced_dialog.recommended"
+                              )
+                            : undefined,
+                        ]
+                          .filter(Boolean)
+                          .join(" • ")}
+                      </span>`
+                    : nothing
+                }
+              </ha-list-item-button>
+            `;
+          })}
+        </ha-list-base>
+      </ha-dialog>
+    `;
+  }
+
+  static styles = css`
+    ha-dialog {
+      --dialog-content-padding: 0;
+      --ha-row-item-padding-inline: var(--ha-space-6);
+    }
+    .description {
+      margin: 0;
+      padding: 0 var(--ha-space-6) var(--ha-space-4);
+      color: var(--secondary-text-color);
+    }
+  `;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "dialog-device-replaced": DialogDeviceReplaced;
+  }
+}
@@ -1,6 +1,7 @@
+import { mdiAlertOutline } from "@mdi/js";
 import type { RenderItemFunction } from "@lit-labs/virtualizer/virtualize";
 import type { HassEntity } from "home-assistant-js-websocket";
-import { html, LitElement, nothing, type PropertyValues } from "lit";
+import { css, html, LitElement, nothing, type PropertyValues } from "lit";
 import { customElement, property, query, state } from "lit/decorators";
 import memoizeOne from "memoize-one";
 import { fireEvent } from "../../common/dom/fire_event";
@@ -13,12 +14,20 @@ import {
  getDevices,
  type DevicePickerItem,
 } from "../../data/device/device_picker";
-import type { DeviceRegistryEntry } from "../../data/device/device_registry";
+import {
+  fetchDeviceCompositeSplits,
+  type DeviceCompositeSplits,
+  type DeviceRegistryEntry,
+} from "../../data/device/device_registry";
 import type { HaEntityPickerEntityFilterFunc } from "../../data/entity/entity";
 import type { HomeAssistant } from "../../types";
 import { brandsUrl } from "../../util/brands-url";
+import "../ha-alert";
+import "../ha-button";
 import "../ha-generic-picker";
 import type { HaGenericPicker } from "../ha-generic-picker";
+import "../ha-svg-icon";
+import { showDeviceReplacedDialog } from "./show-dialog-device-replaced";

 export type HaDevicePickerDeviceFilterFunc = (
  device: DeviceRegistryEntry
@@ -95,6 +104,10 @@ export class HaDevicePicker extends LitElement {

  @state() private _configEntryLookup: Record<string, ConfigEntry> = {};

+  @state() private _compositeSplits?: DeviceCompositeSplits;
+
+  private _loadingCompositeSplits = false;
+
  private _getDevicesMemoized = memoizeOne(
    (
      _devices: HomeAssistant["devices"],
@@ -123,6 +136,29 @@ export class HaDevicePicker extends LitElement {
    this._loadConfigEntries();
  }

+  protected willUpdate(changedProperties: PropertyValues<this>): void {
+    if (
+      !this.hass ||
+      !this.value ||
+      this._compositeSplits !== undefined ||
+      this._loadingCompositeSplits
+    ) {
+      return;
+    }
+    const oldHass = changedProperties.get("hass") as HomeAssistant | undefined;
+    const devicesChanged =
+      changedProperties.has("hass") && this.hass.devices !== oldHass?.devices;
+    if (
+      (changedProperties.has("value") || devicesChanged) &&
+      !this.hass.devices[this.value]
+    ) {
+      // The selected device is not in the registry; it might be a legacy
+      // composite device that was split into separate devices. Fetch the
+      // split map so we can offer to replace the reference.
+      this._loadCompositeSplits();
+    }
+  }
+
  private async _loadConfigEntries() {
    const configEntries = await getConfigEntries(this.hass);
    this._configEntryLookup = Object.fromEntries(
@@ -130,6 +166,43 @@ export class HaDevicePicker extends LitElement {
    );
  }

+  private async _loadCompositeSplits() {
+    this._loadingCompositeSplits = true;
+    try {
+      this._compositeSplits = await fetchDeviceCompositeSplits(this.hass);
+    } catch (_err) {
+      this._compositeSplits = {};
+    } finally {
+      this._loadingCompositeSplits = false;
+    }
+  }
+
+  private _getReplacement = memoizeOne(
+    (
+      value: string | undefined,
+      _devices: HomeAssistant["devices"],
+      compositeSplits: DeviceCompositeSplits | undefined,
+      items: (DevicePickerItem | string)[]
+    ) => {
+      if (!value || !compositeSplits || this.hass.devices[value]) {
+        return undefined;
+      }
+      const split = compositeSplits[value];
+      if (!split) {
+        return undefined;
+      }
+      // Keep only the split devices that pass this picker's filters. In
+      // practice usually exactly one of the split devices matches.
+      const selectableIds = new Set(
+        items
+          .filter((item): item is DevicePickerItem => typeof item !== "string")
+          .map((item) => item.id)
+      );
+      const candidates = split.split_ids.filter((id) => selectableIds.has(id));
+      return { candidates, primaryId: split.primary_id };
+    }
+  );
+
  private _getItems = () =>
    this._getDevicesMemoized(
      this.hass.devices,
@@ -144,49 +217,66 @@ export class HaDevicePicker extends LitElement {
    );

  private _valueRenderer = memoizeOne(
-    (configEntriesLookup: Record<string, ConfigEntry>) => (value: string) => {
-      const deviceId = value;
-      const device = this.hass.devices[deviceId];
+    (
+      configEntriesLookup: Record<string, ConfigEntry>,
+      replacementName: string | undefined
+    ) =>
+      (value: string) => {
+        const deviceId = value;
+        const device = this.hass.devices[deviceId];

-      if (!device) {
-        return html`<span slot="headline">${deviceId}</span>`;
-      }
-
-      const area = getDeviceArea(device, this.hass.areas);
-
-      const deviceName = device ? computeDeviceName(device) : undefined;
-      const areaName = area ? computeAreaName(area) : undefined;
-
-      const primary = deviceName;
-      const secondary = areaName;
-
-      const configEntry = device.primary_config_entry
-        ? configEntriesLookup[device.primary_config_entry]
-        : undefined;
-
-      return html`
-        ${
-          configEntry
-            ? html`<img
+        if (!device) {
+          // When the device was replaced and a replacement is available, show
+          // the replacement device's name. Otherwise fall back to the normal
+          // "not found" display of the raw id.
+          if (replacementName) {
+            return html`
+              <ha-svg-icon
                slot="start"
-                alt=""
-                crossorigin="anonymous"
-                referrerpolicy="no-referrer"
-                src=${brandsUrl(
-                  {
-                    domain: configEntry.domain,
-                    type: "icon",
-                    darkOptimized: this.hass.themes?.darkMode,
-                  },
-                  this.hass.auth.data.hassUrl
-                )}
-              />`
-            : nothing
+                style="color: var(--warning-color)"
+                .path=${mdiAlertOutline}
+              ></ha-svg-icon>
+              <span slot="headline">${replacementName}</span>
+            `;
+          }
+          return html`<span slot="headline">${deviceId}</span>`;
        }
-        <span slot="headline">${primary}</span>
-        <span slot="supporting-text">${secondary}</span>
-      `;
-    }
+
+        const area = getDeviceArea(device, this.hass.areas);
+
+        const deviceName = device ? computeDeviceName(device) : undefined;
+        const areaName = area ? computeAreaName(area) : undefined;
+
+        const primary = deviceName;
+        const secondary = areaName;
+
+        const configEntry = device.primary_config_entry
+          ? configEntriesLookup[device.primary_config_entry]
+          : undefined;
+
+        return html`
+          ${
+            configEntry
+              ? html`<img
+                  slot="start"
+                  alt=""
+                  crossorigin="anonymous"
+                  referrerpolicy="no-referrer"
+                  src=${brandsUrl(
+                    {
+                      domain: configEntry.domain,
+                      type: "icon",
+                      darkOptimized: this.hass.themes?.darkMode,
+                    },
+                    this.hass.auth.data.hassUrl
+                  )}
+                />`
+              : nothing
+          }
+          <span slot="headline">${primary}</span>
+          <span slot="supporting-text">${secondary}</span>
+        `;
+      }
  );

  private _rowRenderer: RenderItemFunction<DevicePickerItem> = (item) => html`
@@ -235,7 +325,31 @@ export class HaDevicePicker extends LitElement {
      this.placeholder ??
      this.hass.localize("ui.components.device-picker.placeholder");

-    const valueRenderer = this._valueRenderer(this._configEntryLookup);
+    const replacement = this._getReplacement(
+      this.value,
+      this.hass.devices,
+      this._compositeSplits,
+      this._getItems()
+    );
+
+    // Only treat the value as "replaced" when there is an available
+    // replacement device; otherwise fall back to normal "not found" behavior.
+    const canReplace = !!replacement?.candidates.length;
+    const replacementName = canReplace
+      ? computeDeviceName(
+          this.hass.devices[
+            replacement!.primaryId &&
+            replacement!.candidates.includes(replacement!.primaryId)
+              ? replacement!.primaryId
+              : replacement!.candidates[0]
+          ]
+        )
+      : undefined;
+
+    const valueRenderer = this._valueRenderer(
+      this._configEntryLookup,
+      replacementName
+    );

    return html`
      <ha-generic-picker
@@ -256,15 +370,84 @@ export class HaDevicePicker extends LitElement {
        .hideClearIcon=${this.hideClearIcon}
        .valueRenderer=${valueRenderer}
        .searchKeys=${deviceComboBoxKeys}
-        .unknownItemText=${this.hass.localize(
-          "ui.components.device-picker.unknown"
-        )}
+        .unknownItemText=${
+          replacement?.candidates.length
+            ? this.hass.localize(
+                "ui.components.device-picker.device_replaced_count",
+                { count: replacement.candidates.length }
+              )
+            : this.hass.localize("ui.components.device-picker.unknown")
+        }
        @value-changed=${this._valueChanged}
      >
      </ha-generic-picker>
+      ${canReplace ? this._renderReplacedAlert(replacement!) : nothing}
    `;
  }

+  private _renderReplacedAlert(replacement: {
+    candidates: string[];
+    primaryId: string | null;
+  }) {
+    const { candidates } = replacement;
+
+    const replacementName =
+      candidates.length === 1
+        ? computeDeviceName(this.hass.devices[candidates[0]])
+        : undefined;
+
+    return html`
+      <ha-alert alert-type="warning">
+        ${
+          replacementName
+            ? this.hass.localize(
+                "ui.components.device-picker.device_replaced_by_one",
+                { device: replacementName }
+              )
+            : this.hass.localize(
+                "ui.components.device-picker.device_replaced_by_multiple",
+                { count: candidates.length }
+              )
+        }
+        <ha-button
+          slot="action"
+          appearance="plain"
+          @click=${this._handleReplace}
+        >
+          ${this.hass.localize("ui.components.device-picker.replace_device")}
+        </ha-button>
+      </ha-alert>
+    `;
+  }
+
+  private _handleReplace = () => {
+    const replacement = this._getReplacement(
+      this.value,
+      this.hass.devices,
+      this._compositeSplits,
+      this._getItems()
+    );
+    if (!replacement?.candidates.length) {
+      return;
+    }
+    const { candidates, primaryId } = replacement;
+    if (candidates.length === 1) {
+      this._setValue(candidates[0]);
+      return;
+    }
+    showDeviceReplacedDialog(this, {
+      originalDeviceId: this.value!,
+      candidates,
+      primaryId,
+      onResolved: (deviceId) => this._setValue(deviceId),
+    });
+  };
+
+  private _setValue(value: string) {
+    this.value = value;
+    fireEvent(this, "value-changed", { value });
+  }
+
  public async open() {
    await this.updateComplete;
    await this._picker?.open();
@@ -281,6 +464,13 @@ export class HaDevicePicker extends LitElement {
    this.hass.localize("ui.components.device-picker.no_match", {
      term: html`<b>‘${search}’</b>`,
    });
+
+  static styles = css`
+    ha-alert {
+      display: block;
+      margin-top: 8px;
+    }
+  `;
 }

 declare global {
@@ -0,0 +1,22 @@
+import { fireEvent } from "../../common/dom/fire_event";
+
+export interface DeviceReplacedDialogParams {
+  /** The removed composite device that is being referenced. */
+  originalDeviceId: string;
+  /** The split devices the reference can be pointed at. */
+  candidates: string[];
+  /** The split device that took over the composite's primary config entry. */
+  primaryId: string | null;
+  /** Called with the device the user picked as replacement. */
+  onResolved: (deviceId: string) => void;
+}
+
+export const showDeviceReplacedDialog = (
+  element: HTMLElement,
+  params: DeviceReplacedDialogParams
+) =>
+  fireEvent(element, "show-dialog", {
+    dialogTag: "dialog-device-replaced",
+    dialogImport: () => import("./dialog-device-replaced"),
+    dialogParams: params,
+  });
@@ -27,6 +27,10 @@ import {
  getDevices,
  type DevicePickerItem,
 } from "../data/device/device_picker";
+import {
+  fetchDeviceCompositeSplits,
+  type DeviceCompositeSplits,
+} from "../data/device/device_registry";
 import type { HaEntityPickerEntityFilterFunc } from "../data/entity/entity";
 import {
  entityComboBoxKeys,
@@ -122,6 +126,10 @@ export class HaTargetPicker extends SubscribeMixin(LitElement) {

  @state() private _configEntryLookup: Record<string, ConfigEntry> = {};

+  @state() private _compositeSplits?: DeviceCompositeSplits;
+
+  private _loadingCompositeSplits = false;
+
  @state()
  @consume({ context: labelsContext, subscribe: true })
  private _labelRegistry!: LabelRegistryEntry[];
@@ -211,6 +219,24 @@ export class HaTargetPicker extends SubscribeMixin(LitElement) {
      this._loadConfigEntries();
    }

+    const devicesChanged =
+      changedProps.has("hass") &&
+      this.hass.devices !== changedProps.get("hass")?.devices;
+    if (
+      (changedProps.has("value") || devicesChanged) &&
+      this.hass &&
+      this._compositeSplits === undefined &&
+      !this._loadingCompositeSplits &&
+      this.value?.device_id &&
+      ensureArray(this.value.device_id).some(
+        (deviceId) => !this.hass.devices[deviceId]
+      )
+    ) {
+      // A referenced device is missing from the registry; it might be a legacy
+      // composite device that was split. Fetch the split map to offer a fix.
+      this._loadCompositeSplits();
+    }
+
    if (
      this._pendingEntityId &&
      changedProps.has("hass") &&
@@ -297,6 +323,7 @@ export class HaTargetPicker extends SubscribeMixin(LitElement) {
                    .hass=${this.hass}
                    type="device"
                    .itemId=${device_id}
+                    .compositeSplits=${this._compositeSplits}
                    @remove-target-item=${this._handleRemove}
                    @expand-target-item=${this._handleExpand}
                  ></ha-target-picker-value-chip>
@@ -390,6 +417,7 @@ export class HaTargetPicker extends SubscribeMixin(LitElement) {
                <ha-target-picker-item-group
                  @remove-target-item=${this._handleRemove}
                  @replace-target-item=${this._handleReplace}
+                  @migrate-target-item=${this._handleMigrate}
                  type="device"
                  .hass=${this.hass}
                  .items=${{ device: deviceIds }}
@@ -398,6 +426,7 @@ export class HaTargetPicker extends SubscribeMixin(LitElement) {
                  .includeDomains=${this.includeDomains}
                  .includeDeviceClasses=${this.includeDeviceClasses}
                  .primaryEntitiesOnly=${this.primaryEntitiesOnly}
+                  .compositeSplits=${this._compositeSplits}
                >
                </ha-target-picker-item-group>
              `
@@ -1175,6 +1204,31 @@ export class HaTargetPicker extends SubscribeMixin(LitElement) {
    );
  }

+  private async _loadCompositeSplits() {
+    this._loadingCompositeSplits = true;
+    try {
+      this._compositeSplits = await fetchDeviceCompositeSplits(this.hass);
+    } catch (_err) {
+      this._compositeSplits = {};
+    } finally {
+      this._loadingCompositeSplits = false;
+    }
+  }
+
+  private _handleMigrate(
+    ev: HASSDomEvent<HASSDomEvents["migrate-target-item"]>
+  ) {
+    const { id, replacements } = ev.detail;
+    let value = this._removeItem(this.value, "device", id);
+    for (const replacement of replacements) {
+      value = this._addTargetToValue(value, {
+        type: "device",
+        id: replacement,
+      });
+    }
+    fireEvent(this, "value-changed", { value });
+  }
+
  private _renderRow = (
    item:
      | PickerComboBoxItem
@@ -1357,6 +1411,7 @@ declare global {
    "remove-target-item": TargetItem;
    "expand-target-item": TargetItem;
    "replace-target-item": TargetItem;
+    "migrate-target-item": { id: string; replacements: string[] };
    "remove-target-group": string;
  }
 }
@@ -1,5 +1,6 @@
 import { css, html, LitElement, nothing } from "lit";
 import { customElement, property } from "lit/decorators";
+import type { DeviceCompositeSplits } from "../../data/device/device_registry";
 import type { HaEntityPickerEntityFilterFunc } from "../../data/entity/entity";
 import type { TargetType, TargetTypeFloorless } from "../../data/target";
 import type { HomeAssistant } from "../../types";
@@ -45,6 +46,9 @@ export class HaTargetPickerItemGroup extends LitElement {
  @property({ type: Boolean, attribute: "primary-entities-only" })
  public primaryEntitiesOnly?: boolean;

+  @property({ attribute: false })
+  public compositeSplits?: DeviceCompositeSplits;
+
  protected render() {
    let count = 0;
    Object.values(this.items).forEach((items) => {
@@ -80,6 +84,7 @@ export class HaTargetPickerItemGroup extends LitElement {
                    .includeDomains=${this.includeDomains}
                    .includeDeviceClasses=${this.includeDeviceClasses}
                    .primaryEntitiesOnly=${this.primaryEntitiesOnly}
+                    .compositeSplits=${this.compositeSplits}
                  ></ha-target-picker-item-row>`
              )
            : nothing
@@ -34,7 +34,10 @@ import { computeRTL } from "../../common/util/compute_rtl";
 import type { AreaRegistryEntry } from "../../data/area/area_registry";
 import { getConfigEntry } from "../../data/config_entries";
 import { labelsContext } from "../../data/context";
-import type { DeviceRegistryEntry } from "../../data/device/device_registry";
+import type {
+  DeviceCompositeSplits,
+  DeviceRegistryEntry,
+} from "../../data/device/device_registry";
 import type { HaEntityPickerEntityFilterFunc } from "../../data/entity/entity";
 import type { FloorRegistryEntry } from "../../data/floor_registry";
 import { domainToName } from "../../data/integration";
@@ -108,6 +111,9 @@ export class HaTargetPickerItemRow extends LitElement {
  @property({ type: Boolean, attribute: "primary-entities-only" })
  public primaryEntitiesOnly?: boolean;

+  @property({ attribute: false })
+  public compositeSplits?: DeviceCompositeSplits;
+
  @state() private _iconImg?: string;

  @state() private _domainName?: string;
@@ -128,6 +134,15 @@ export class HaTargetPickerItemRow extends LitElement {
    const { name, context, iconPath, fallbackIconPath, stateObject, notFound } =
      this._itemData(this.type, this.itemId);

+    const replacement =
+      this.type === "device" && notFound
+        ? this._getReplacement(this.itemId)
+        : undefined;
+    // Only surface the "replaced" state when there is at least one available
+    // replacement device to migrate to. If every replacement device was
+    // deleted (or filtered out), fall back to the plain "not found" state.
+    const canMigrate = !!replacement?.candidates.length;
+
    const showEntities = this.type !== "entity" && !notFound;

    const entries = this.parentEntries || this._entries;
@@ -174,15 +189,20 @@ export class HaTargetPickerItemRow extends LitElement {
        }
      </div>

-      <div slot="headline">${name}</div>
+      <div slot="headline">${(canMigrate && replacement?.name) || name}</div>
      ${
        notFound || (context && !this.hideContext)
          ? html`<span slot="supporting-text"
              >${
                notFound
-                  ? this.hass.localize(
-                      `ui.components.target-picker.${this.type}_not_found`
-                    )
+                  ? canMigrate
+                    ? this.hass.localize(
+                        "ui.components.target-picker.device_replaced",
+                        { count: replacement!.candidates.length }
+                      )
+                    : this.hass.localize(
+                        `ui.components.target-picker.${this.type}_not_found`
+                      )
                  : context
              }</span
            >`
@@ -229,6 +249,21 @@ export class HaTargetPickerItemRow extends LitElement {
            `
          : nothing
      }
+      ${
+        canMigrate
+          ? html`
+              <button
+                class="main link migrate"
+                slot="end"
+                @click=${this._migrate}
+              >
+                ${this.hass.localize(
+                  "ui.components.target-picker.replace_device"
+                )}
+              </button>
+            `
+          : nothing
+      }
      ${
        !this.expand && !this.subEntry
          ? html`
@@ -707,6 +742,51 @@ export class HaTargetPickerItemRow extends LitElement {
    });
  }

+  // Returns the split devices that replaced a removed composite device and
+  // pass this row's filters, or undefined if the item is not a replaced device.
+  private _getReplacement(item: string) {
+    const split = this.compositeSplits?.[item];
+    if (!split || this.hass.devices[item]) {
+      return undefined;
+    }
+    const candidates = split.split_ids.filter((id) => {
+      const device = this.hass.devices[id];
+      return (
+        device &&
+        deviceMeetsFilter(
+          device,
+          this.hass.entities,
+          this.deviceFilter,
+          this.includeDomains,
+          this.includeDeviceClasses,
+          this.hass.states,
+          this.entityFilter,
+          !this.primaryEntitiesOnly
+        )
+      );
+    });
+    // Display the replaced reference using the primary replacement device's
+    // name instead of the removed composite device id. Fall back to the first
+    // available candidate if the primary device itself was deleted.
+    const nameDevice =
+      (split.primary_id && this.hass.devices[split.primary_id]) ||
+      (candidates.length ? this.hass.devices[candidates[0]] : undefined);
+    const name = nameDevice ? computeDeviceName(nameDevice) : undefined;
+    return { candidates, name };
+  }
+
+  private _migrate = (ev: MouseEvent) => {
+    ev.stopPropagation();
+    const replacement = this._getReplacement(this.itemId);
+    if (!replacement?.candidates.length) {
+      return;
+    }
+    fireEvent(this, "migrate-target-item", {
+      id: this.itemId,
+      replacements: replacement.candidates,
+    });
+  };
+
  private _openDetails(ev: MouseEvent) {
    ev.stopPropagation();
    showTargetDetailsDialog(this, {
@@ -746,6 +826,13 @@ export class HaTargetPickerItemRow extends LitElement {
        color: var(--ha-color-on-warning-normal);
      }

+      .migrate {
+        align-self: center;
+        white-space: nowrap;
+        font-weight: var(--ha-font-weight-medium);
+        color: var(--ha-color-on-warning-normal);
+      }
+
      .replaceable {
        cursor: pointer;
      }
@@ -1,6 +1,7 @@
 import "@home-assistant/webawesome/dist/components/tag/tag";
 import { consume } from "@lit/context";
 import {
+  mdiAlertOutline,
  mdiDevices,
  mdiHome,
  mdiLabel,
@@ -9,6 +10,7 @@ import {
 } from "@mdi/js";
 import { css, html, LitElement, nothing } from "lit";
 import { customElement, property, state } from "lit/decorators";
+import { classMap } from "lit/directives/class-map";
 import memoizeOne from "memoize-one";
 import { computeCssColor } from "../../common/color/compute-color";
 import { hex2rgb } from "../../common/color/convert-color";
@@ -19,6 +21,7 @@ import { computeStateName } from "../../common/entity/compute_state_name";
 import { slugify } from "../../common/string/slugify";
 import { getConfigEntry } from "../../data/config_entries";
 import { labelsContext } from "../../data/context";
+import type { DeviceCompositeSplits } from "../../data/device/device_registry";
 import { domainToName } from "../../data/integration";
 import type { LabelRegistryEntry } from "../../data/label/label_registry";
 import type { TargetType } from "../../data/target";
@@ -39,6 +42,9 @@ export class HaTargetPickerValueChip extends LitElement {

  @property({ attribute: "item-id" }) public itemId!: string;

+  @property({ attribute: false })
+  public compositeSplits?: DeviceCompositeSplits;
+
  @state() private _domainName?: string;

  @state() private _iconImg?: string;
@@ -51,38 +57,74 @@ export class HaTargetPickerValueChip extends LitElement {
    const { name, iconPath, fallbackIconPath, stateObject, color } =
      this._itemData(this.type, this.itemId);

+    const split =
+      this.type === "device" && !this.hass.devices?.[this.itemId]
+        ? this.compositeSplits?.[this.itemId]
+        : undefined;
+    // Show the replaced reference using the primary replacement device's name,
+    // falling back to the first still-existing split device if the primary
+    // device itself was deleted. If no replacement device exists at all, fall
+    // back to the normal "not found" display.
+    const replacementDevice = split
+      ? (split.primary_id && this.hass.devices?.[split.primary_id]) ||
+        split.split_ids
+          .map((id) => this.hass.devices?.[id])
+          .find((device) => device)
+      : undefined;
+    const replaced = !!replacementDevice;
+    const replacedName = replacementDevice
+      ? computeDeviceNameDisplay(
+          replacementDevice,
+          this.hass.localize,
+          this.hass.states
+        )
+      : undefined;
+
    return html`
      <wa-tag
        pill
        with-remove
-        class=${this.type}
+        class=${classMap({ [this.type]: true, replaced })}
        style=${color ? `--color: rgb(${color});` : ""}
        @wa-remove=${this._removeItem}
      >
        <div class="icon">
          ${
-            iconPath
-              ? html`<ha-icon .icon=${iconPath}></ha-icon>`
-              : this._iconImg
-                ? html`<img
-                    alt=${this._domainName || ""}
-                    width="24"
-                    crossorigin="anonymous"
-                    referrerpolicy="no-referrer"
-                    src=${this._iconImg}
-                  />`
-                : fallbackIconPath
-                  ? html`<ha-svg-icon .path=${fallbackIconPath}></ha-svg-icon>`
-                  : stateObject
-                    ? html`<ha-state-icon
-                        .stateObj=${stateObject}
-                      ></ha-state-icon>`
-                    : nothing
+            replaced
+              ? html`<ha-svg-icon .path=${mdiAlertOutline}></ha-svg-icon>`
+              : iconPath
+                ? html`<ha-icon .icon=${iconPath}></ha-icon>`
+                : this._iconImg
+                  ? html`<img
+                      alt=${this._domainName || ""}
+                      width="24"
+                      crossorigin="anonymous"
+                      referrerpolicy="no-referrer"
+                      src=${this._iconImg}
+                    />`
+                  : fallbackIconPath
+                    ? html`<ha-svg-icon
+                        .path=${fallbackIconPath}
+                      ></ha-svg-icon>`
+                    : stateObject
+                      ? html`<ha-state-icon
+                          .stateObj=${stateObject}
+                        ></ha-state-icon>`
+                      : nothing
          }
        </div>
-        <span class="name"> ${name} </span>
+        <span class="name">
+          ${
+            replaced
+              ? replacedName ||
+                this.hass.localize(
+                  "ui.components.target-picker.replaced_device"
+                )
+              : name
+          }
+        </span>
        ${
-          this.type === "entity"
+          this.type === "entity" || replaced
            ? nothing
            : html`<ha-tooltip .for="expand-${slugify(this.itemId)}"
                  >${this.hass.localize(
@@ -125,7 +167,7 @@ export class HaTargetPickerValueChip extends LitElement {
    if (type === "device") {
      const device = this.hass.devices?.[itemId];

-      if (device.primary_config_entry) {
+      if (device?.primary_config_entry) {
        this._getDeviceDomain(device.primary_config_entry);
      }

@@ -240,6 +282,11 @@ export class HaTargetPickerValueChip extends LitElement {
      --background-color: var(--color);
      --icon-primary-color: var(--primary-text-color);
    }
+    wa-tag.replaced {
+      border-color: var(--ha-color-border-warning-normal, var(--warning-color));
+      --background-color: var(--warning-color);
+      color: var(--ha-color-on-warning-normal, var(--warning-color));
+    }

    .name {
      overflow: hidden;
@@ -1,3 +1,4 @@
+import type { Connection } from "home-assistant-js-websocket";
 import { computeStateName } from "../../common/entity/compute_state_name";
 import { caseInsensitiveStringCompare } from "../../common/string/compare";
 import type { HomeAssistant } from "../../types";
@@ -54,6 +55,52 @@ export interface DeviceRegistryEntryMutableParams {
  labels?: string[];
 }

+/**
+ * Describes how a legacy composite device (that lived on multiple config
+ * entries) was split into separate devices. The composite device no longer
+ * exists in the registry; references to it (in automations, targets, ...) now
+ * need to point at one or more of the split devices instead.
+ */
+export interface DeviceCompositeSplit {
+  /** Ids of the devices that replaced the composite device. */
+  split_ids: string[];
+  /** The split device that took over the composite's primary config entry. */
+  primary_id: string | null;
+}
+
+/** Map of removed composite device id -> its split information. */
+export type DeviceCompositeSplits = Record<string, DeviceCompositeSplit>;
+
+// The composite split migration in core is a one-time operation, so the split
+// map is static for the lifetime of the connection. Cache the request per
+// connection so it is fetched once and shared across all pickers, instead of
+// being requested again by every device/target picker.
+const compositeSplitsCache = new WeakMap<
+  Connection,
+  Promise<DeviceCompositeSplits>
+>();
+
+export const fetchDeviceCompositeSplits = (
+  hass: HomeAssistant
+): Promise<DeviceCompositeSplits> => {
+  const conn = hass.connection;
+
+  let request = compositeSplitsCache.get(conn);
+  if (!request) {
+    request = hass
+      .callWS<DeviceCompositeSplits>({
+        type: "config/device_registry/list_composite_splits",
+      })
+      .catch((err) => {
+        // Don't cache failures so the next caller retries.
+        compositeSplitsCache.delete(conn);
+        throw err;
+      });
+    compositeSplitsCache.set(conn, request);
+  }
+  return request;
+};
+
 export const fallbackDeviceName = (
  hass: HomeAssistant,
  entities: EntityRegistryEntry[] | EntityRegistryDisplayEntry[] | string[]
@@ -791,6 +791,9 @@
        "device_not_found": "Device not found",
        "entity_not_found": "Entity not found",
        "label_not_found": "Label not found",
+        "replaced_device": "Replaced device",
+        "device_replaced": "Replaced by {count} {count, plural,\n one {device}\n other {devices}\n}",
+        "replace_device": "Replace",
        "devices_count": "{count} {count, plural,\n one {device}\n other {devices}\n}",
        "entities_count": "{count} {count, plural,\n one {entity}\n other {entities}\n}",
        "target_details": "Target details",
@@ -910,7 +913,16 @@
        "unnamed_device": "Unnamed device",
        "no_area": "No area",
        "placeholder": "Select a device",
-        "unknown": "Unknown device selected"
+        "unknown": "Unknown device selected",
+        "device_replaced_count": "Replaced by {count} {count, plural,\n one {device}\n other {devices}\n}",
+        "device_replaced_by_one": "This device was replaced by {device}.",
+        "device_replaced_by_multiple": "This device was replaced by {count} devices.",
+        "replace_device": "Replace",
+        "replaced_dialog": {
+          "title": "Replace device",
+          "description": "This device was replaced by multiple devices. Choose which one to use.",
+          "recommended": "Recommended"
+        }
      },
      "category-picker": {
        "clear": "Clear",