Blog

Short answer: if Home Assistant says it cannot restart because the configuration is not valid, do not keep restarting and do not delete large sections of YAML. First run the built-in configuration check, read the first concrete error, fix only that section, and validate again before reloading or restarting.

What the message means

Home Assistant checks configuration before a reload or restart. The failure may be a YAML syntax problem, an invalid option, a missing integration platform, an incorrect indentation level, or a file saved in the wrong encoding. The first error is usually the most useful one.

Safest diagnostic sequence

1. Stop changing multiple files and note the last edit.
2. Open Settings → Developer tools → YAML and run the configuration check. On Home Assistant OS or a supported CLI setup, use ha core check.
3. Read the first specific file path, line number, integration name, or error message.
4. Undo only the last risky change or restore the smallest known-good block.
5. Run the check again before reloading or restarting.

Common causes

Indentation or punctuation

Check tabs, mismatched quotes, missing colons, duplicate keys, and list items that are not aligned. Compare the affected block with the current integration documentation.

Removed or renamed platforms

An old platform: entry can fail after an integration changes or a custom component is removed. Confirm whether the configuration should be migrated or removed.

Invalid options

Treat “extra keys not allowed” as a documentation mismatch, not a reason to guess. Check the current integration page and release notes.

Encoding or included files

Home Assistant documentation notes that configuration files must be UTF-8 encoded. If you use !include or packages, follow the path and inspect the child file too.

How to interpret the result

Validation passes: the configuration is acceptable to the check, but devices can still be offline. The same error remains: you may have edited the wrong file or missed an included file. A new error appears: fix one concrete error at a time and validate after each change.

Recovery if the UI will not restart

Use the last known-good backup or snapshot before making broad edits. Restore the smallest affected file first. Avoid deleting the whole configuration directory.

Prevention

• Run a configuration check before every restart after YAML edits.
• Make one focused change at a time.
• Keep dated backups before upgrades.
• Prefer UI-configured integrations when supported.

FAQ

Can I restart anyway?

Not safely. The warning exists to prevent a restart with a known-invalid configuration.

Will a configuration check find offline devices?

No. It checks configuration syntax and supported structure.

Should I delete the line named in the error?

Only if current documentation confirms it is obsolete or invalid.

Sources: Home Assistant troubleshooting; Home Assistant configuration and validation; Home Assistant OS configuration check.

Testing disclosure: Documentation-based guide; no hands-on testing on a specific installation is claimed.

Direct answer: The warning “This entity is no longer being provided by the integration” means Home Assistant still has an entity-registry record, but the integration that created it did not create a matching live entity during the current startup or reload. Do not delete it immediately. First determine whether it is a truly retired entity, a renamed or duplicated replacement, an integration that failed to load, or—especially with MQTT—a discovery message that was not republished.

What the warning actually tells you

Home Assistant separates an entity’s saved registry record from the live entity object supplied by an integration. The registry keeps details such as the entity ID, unique ID, device association, name, and whether the entity was disabled. If the saved record exists but no current entity backs it, Home Assistant can show the record as no longer provided.

This is different from an ordinary unavailable state. An unavailable entity may still be actively supplied by its integration even though the device or service cannot currently report a state. “No longer being provided” points to the relationship between the registry and the integration’s present setup.

Ranked causes

1. The integration renamed, replaced, or stopped creating the entity

An update, device firmware change, configuration change, or integration migration can alter which entities are created. The old registry record remains because deleting it automatically could break dashboards, history references, scripts, scenes, and automations. A replacement may appear under a new entity ID or device entry.

2. The integration failed to finish setup

If several entities from the same integration show the warning at once, the problem is unlikely to be dozens of independent entity failures. Check Settings → Devices & services for setup, authentication, dependency, or communication errors. Then inspect logs from the time Home Assistant started or the integration was reloaded.

3. MQTT discovery was not replayed

MQTT-discovered entities require valid discovery configuration. Home Assistant’s MQTT documentation explains that after a restart, discovered items with a unique ID can remain unavailable until discovery messages are received again. Publishers commonly solve this with retained discovery configuration or by republishing configuration after Home Assistant’s birth message. An empty discovery payload can also remove a previously discovered device.

Do not purge retained topics blindly. Retained messages can restore entities, but stale retained discovery can also recreate ghost entities. Identify the exact discovery topic and current payload first.

4. The device or integration created a duplicate unique identity

A replacement entity ending in _2 is a clue, not proof. Compare the integration, device, unique ID, state updates, and history. The working replacement may have been created because a device identifier, discovery topic, MAC address format, or integration entry changed. Renaming it prematurely can hide the evidence.

5. The entity is disabled, deprecated, or intentionally removed

Some integrations disable less-used entities by default, and integrations can retire entities when capabilities change. A disabled entity is not loaded into Home Assistant. Confirm whether the entity is marked disabled, deprecated, diagnostic-only, or no longer supported before treating it as broken.

Safest diagnostic sequence

Step 1: Preserve references

Create a current Home Assistant backup. Record the warning, entity ID, integration, device, unique ID if visible, last-updated time, and any apparent replacement entity. Search dashboards, automations, scripts, scenes, templates, and helpers for the old entity ID. Do not expose tokens, passwords, broker credentials, network keys, or unredacted backups.

Step 2: Decide whether the integration is healthy

Open the integration page and check whether other entities from the same integration still update. If many fail together, stay at the integration layer: authentication, connectivity, configuration entry, dependency, or startup error. If only one registry record is affected while its siblings work, compare that entity with the device’s current capabilities and replacement entities.

Step 3: Check the first meaningful log entry

Restarting repeatedly can bury the useful evidence. Reproduce the problem once, note the time, and read the first related warning or error—not only later consequences. Separate setup failures, authentication failures, timeouts, invalid configuration, missing dependencies, and device-discovery changes.

Step 4: For MQTT, prove the discovery path

Confirm that the MQTT integration is connected to the intended broker. Verify that the publisher—such as Zigbee2MQTT or another bridge—is online and publishing current discovery configuration after Home Assistant starts. Compare the affected entity’s discovery topic and unique ID with a working entity. Do not publish test payloads to production topics unless you have a broker backup and understand the publisher’s discovery format.

If your symptom began after a restart, also use the MQTT entities unavailable after restart guide. If the entity repeatedly changes between available and unavailable rather than showing “not provided,” use the MQTT availability flapping diagnostic.

Step 5: Compare old and replacement entities

Place the old and new entity IDs side by side. Confirm which one receives fresh states and controls the physical device. Compare device association, integration entry, unit, device class, and unique ID. Update one low-risk dashboard card first and verify it through a normal state change. Then update automations and templates carefully.

If many duplicates appeared after an update, follow the duplicate-device repair guide before merging or deleting records.

Step 6: Reload only when evidence supports it

If the integration is otherwise healthy and supports reload, one controlled reload can show whether the entity is recreated. For an authentication problem, use Reauthenticate or Reconfigure where offered. Restart Home Assistant only when the logs or integration instructions justify it. Do not remove and re-add an entire integration to repair one orphaned record unless you have documented the downstream impact.

When it is safe to delete the old entity

Delete the registry record only when all of these are true:

• the integration and device are healthy;
• the old entity has a confirmed working replacement or is intentionally retired;
• dashboards, automations, scripts, scenes, templates, and helpers no longer reference it;
• you have preserved any history or identifier information you still need; and
• a current backup exists.

After deletion, restart only if the integration’s documentation calls for it. If the entity returns, the source is still advertising or creating it. That is evidence to inspect discovery or integration configuration—not a reason to delete it repeatedly.

Verification checklist

1. The integration loads without a repeating setup error.
2. The intended entity receives a fresh state after a real device change.
3. A harmless command works, when the entity is controllable.
4. No automation or dashboard still points to the orphaned ID.
5. The result survives an ordinary integration reload or planned Home Assistant restart.
6. No duplicate device or _2 entity reappears.

Prevention

• Back up before Home Assistant, integration, broker, or bridge migrations.
• Document entity IDs used by critical automations.
• For MQTT publishers, follow Home Assistant’s discovery, birth-message, and retained-message guidance.
• Change one identity-related setting at a time and verify after each change.
• Review release notes before updates that migrate device or entity registries.

FAQ

Is “not provided” the same as “unavailable”?

No. Unavailable can mean a live entity cannot currently obtain a state. “No longer being provided” means the saved registry entry is not backed by a live entity from its integration.

Will deleting the entity fix the integration?

No. Deletion removes the orphaned registry record. It does not repair authentication, MQTT discovery, a failed setup, or device connectivity.

Why did a second entity appear with _2?

Home Assistant encountered an entity-ID collision or a new unique identity. Compare old and new records before renaming either one.

Should I remove and re-add the integration?

Usually not as a first step. Re-adding can change identifiers and break references. Diagnose setup, authentication, discovery, and replacement entities first.

Primary sources

• Home Assistant: state and state objects
• Home Assistant developer architecture: devices, services, and entity registry
• Home Assistant MQTT discovery and availability documentation
• Home Assistant configuration troubleshooting

Reviewed against official documentation on September 30, 2026.

Direct answer: When a Home Assistant automation runs twice, do not add a delay or change its run mode first. Open two traces and compare the trigger description, trigger ID, timestamp and action path. Most duplicate-looking runs come from two valid triggers, a state trigger that matches more transitions than intended, the same automation loaded twice, an event emitted twice by the source integration, or two different automations calling the same action. The trace evidence tells you which branch to fix.

First decide what “twice” means

Two notifications, two light commands or two logbook entries do not necessarily prove that one automation ran twice. A single run can call the same action from two branches, a script can repeat an action, a device can report the same change twice, and two separate automations can target the same service. Conversely, one automation can legitimately start two runs milliseconds apart.

Use traces as the source of truth. If there are two trace entries with different run IDs, Home Assistant started the automation twice. If there is one trace with two action calls, the duplication is inside the action sequence, script or downstream integration. If there is only one action call but the device responds twice, investigate the target integration or device rather than the automation trigger.

Preserve the evidence before reloading

Home Assistant stores a limited number of traces by default. A reload or edit can make the original state harder to reconstruct. Open both traces and note the exact time, trigger, changed entity, from/to values and path through conditions and choose blocks. Export or copy only the minimum sanitized details required. Remove tokens, webhook IDs, personal locations, device serials, public URLs and notification contents.

For YAML automations, Home Assistant documentation allows the number of stored traces to be increased with the trace stored_traces option. Do this only when the problem is intermittent and existing traces are being overwritten; it does not repair duplicate execution.

Ranked cause 1: two triggers are both valid

Multiple triggers in one automation are evaluated independently. If a motion sensor changes state and a related helper or template changes moments later, both may start the automation. Time, sun, state and event triggers can also overlap at a boundary. Give each trigger a unique ID and compare trigger.id in the trace. The IDs turn an ambiguous duplicate into a measurable pattern.

triggers:
  - trigger: state
    entity_id: binary_sensor.kitchen_motion
    to: "on"
    id: motion_started
  - trigger: state
    entity_id: input_boolean.kitchen_override
    to: "on"
    id: override_started

If either trigger is sufficient, two runs may be correct. Prevent the duplicate at the logic level: choose one source of truth, add a condition that excludes the overlapping case, or branch by trigger ID so both triggers do not execute the same action. Do not use a blanket delay as a substitute for understanding the overlap.

Ranked cause 2: a state trigger matches more transitions than intended

A state trigger without a to or from filter can fire when the entity changes state and, depending on the entity and configuration, attribute changes may also matter. A template trigger can become true again after briefly returning false. Numeric thresholds trigger when crossing the boundary, not continuously, but noisy measurements can cross back and forth.

In each trace, inspect from_state and to_state. If the meaningful state is identical but an attribute changed, narrow the trigger. If the state bounced off and on, fix the noisy source if possible or use a documented duration only when the desired behavior truly requires the state to remain stable. Remember that Home Assistant’s for option does not survive an automation reload or Home Assistant restart.

Ranked cause 3: the same automation is loaded twice

This occurs when equivalent logic exists in the UI and YAML, when an automation was copied and renamed, or when an include causes the same file to be referenced unexpectedly. Search the automation list for the target entity, notification text or distinctive alias. In YAML, confirm that each automation has a unique ID and that automations.yaml remains a list.

Do not remove files blindly. Disable one suspected duplicate, trigger the original condition once, then review traces. If the second run disappears, document which definition remains authoritative before deleting or consolidating anything.

Ranked cause 4: two automations call the same script or service

A duplicated outcome may come from different parents. Search for the service call, script entity, scene, notification message or target entity across automations and scripts. A script trace can show two callers even when each parent automation ran only once. The clean repair is usually to consolidate the shared decision into one automation or make the script idempotent where practical.

Idempotent means a repeated request leaves the system in the same safe state. Turning a light on is often naturally idempotent; sending a notification, incrementing a counter, unlocking a door or making an API request may not be. High-impact actions deserve explicit guards and verification.

Ranked cause 5: the source integration emits two events

Some devices expose both a state change and an event. A button integration may create a device trigger plus an event trigger for the same press. MQTT can deliver retained or repeated messages depending on publisher behavior and quality-of-service configuration. Mobile apps, webhooks and cloud integrations can retry requests.

Compare event data and timestamps in the traces. If the automation received two genuinely separate source events, the trigger is behaving as configured. Correct the publisher when possible. If correction is impossible, use a narrow guard based on a stable event identifier or a short helper-based deduplication window that matches the source behavior. Document the tradeoff: any deduplication rule can suppress legitimate rapid actions.

Ranked cause 6: actions repeat inside one run

Open the trace timeline and count action nodes. Check repeat blocks, parallel sequences, choose branches, scripts and wait/restart paths. A common mistake is to place the same service call before and after a choose block, or to call a script directly and again through a scene or another script.

Fix the duplicated branch rather than changing trigger behavior. Retest the automation manually only after confirming that manual execution is safe; the Run actions control skips normal trigger timing and can make destructive or noisy actions happen immediately.

Why automation mode is not the first fix

Home Assistant modes control what happens when a new run starts while another is active. Single rejects a new overlapping run; restart stops the old run and starts the new one; queued waits; parallel allows independent runs. A mode can change the visible symptom, but it does not explain why two triggers occurred.

If an automation finishes in 100 milliseconds and the second trigger arrives later, mode single will not block it. If you switch to restart, the first run may be interrupted halfway. If you use queued, both unwanted runs may still execute. Select mode based on the intended concurrency after fixing trigger logic.

A privacy-safe trace comparison

Run A
time: 2026-09-29 18:42:10.218
trigger_id: motion_started
entity: binary_sensor.room_motion
from: "off"
to: "on"
action_path: choose/0/sequence/0

Run B
time: 2026-09-29 18:42:10.463
trigger_id: occupancy_started
entity: binary_sensor.room_occupancy
from: "off"
to: "on"
action_path: choose/0/sequence/0

This sanitized example shows two independent triggers reaching the same action 245 milliseconds apart. The evidence points to overlapping motion and occupancy logic, not a Home Assistant scheduler that randomly duplicated one run. Replace real entity names and timestamps when sharing logs publicly.

Common duplicate-run patterns

At Home Assistant startup: An automation may have a Home Assistant start trigger while the same entities also restore or update their state. Compare trigger IDs. If both paths are intentional, decide whether startup should initialize state silently or perform the normal outward action. Avoid sending duplicate alerts simply because several entities become available together.

At sunrise, sunset or a scheduled minute: A time trigger can overlap with a sun, schedule or template trigger that becomes true at nearly the same moment. Use one clock source for the action or branch explicitly so the fallback does not duplicate the primary trigger.

After an automation reload: Reloading attaches the current trigger definitions. It should not be treated as a routine cure for duplicates. If behavior changes only after reload, inspect whether YAML and UI definitions differ, whether a custom integration registers listeners correctly, and whether the issue returns after the next edit or restart.

After reconnecting MQTT or another event source: A retained message, restored entity state or publisher retry can reproduce an apparently old condition. Compare message payloads and source timestamps rather than assuming the automation engine replayed a run. Do not delete retained messages globally; identify the topic and publisher first.

Only when actions take a long time: This pattern makes concurrency mode relevant. If a second trigger arrives while the first sequence is waiting, mode parallel may create two active paths, queued may preserve both, restart may abandon the first, and single may reject the second. Choose the mode that matches the intended physical behavior and include timeouts for waits that could otherwise remain open.

Do not create a fragile cooldown

A cooldown helper can be appropriate for a genuinely noisy source, but it must have a defined duration and consequence. A five-second lockout that hides a duplicate door event could also suppress a real reopen. Before adding one, measure the duplicate interval from traces, decide the fastest legitimate repeat, and choose a guard narrower than that legitimate behavior.

For notifications, consider whether the message can be keyed to an event ID or state transition. For counters and paid API calls, verify that a repeated request cannot create financial or operational harm. For locks, covers, garage doors and alarms, prefer fixing the source and adding explicit safety conditions over relying on a timer.

Safest repair sequence

• Create a current backup before editing important automations.
• Capture the two traces and identify whether there are two runs or one run with two actions.
• Assign trigger IDs if the automation has multiple triggers.
• Narrow state triggers with explicit to/from values where that matches the intent.
• Search for duplicate automations and other parents calling the same script or service.
• Change one cause only. Reload automations if you edited YAML; do not restart the whole host unless required.
• Trigger one controlled test and inspect the new trace.
• Test again after the source has been idle long enough to reproduce the original condition.
• Verify the physical outcome, notification count and Logbook entry.
• Record the final change and keep the evidence until the behavior remains stable.

Verification matrix

• Two traces, different trigger IDs: overlapping triggers; fix conditions or choose a source of truth.
• Two traces, same trigger ID: inspect bouncing state, repeated events, duplicate definitions or publisher retries.
• One trace, two action nodes: repair the action sequence, choose/repeat block or child script.
• One trace, one action call, device acts twice: investigate the integration, transport or device.
• No trace for one outcome: another automation, integration or external platform probably caused it.

Prevention

Name automations and scripts for the outcome they own. Use unique IDs, assign trigger IDs, avoid duplicating the same decision across UI and YAML, and keep high-impact actions centralized. Store enough traces to cover the diagnostic window without retaining unnecessary sensitive details. After Home Assistant or integration updates, test automations that send messages, unlock doors, operate covers, change climate settings or call paid APIs.

Use the automation-not-triggering guide when the opposite failure occurs. Sanitize evidence with the Troubliq Log Sanitizer, and use the Error Decoder for an exact message or warning.

When to escalate

Escalate when two traces show one integration producing reproducible duplicate events, when the trace data contradicts the documented mode behavior, or when duplication began immediately after a known update and persists in a minimal test. Include Home Assistant Core version, installation type, sanitized automation YAML, two traces, relevant integration version and the smallest reproduction. Do not publish secrets or an entire configuration archive.

Official sources and review record

• Home Assistant: Automations in YAML.
• Home Assistant: Automation modes.
• Home Assistant: Automation triggers.
• Home Assistant: Automation actions.

Last reviewed September 29, 2026. Photo credit: Luke Chesser via Unsplash.

When older accessories disappear after new Home Assistant entities are exposed to Apple Home, the bridge may be overloaded, filtered differently, or represented by a changed configuration. The safest repair is to reduce and stabilize the bridge rather than repeatedly deleting it from both systems.

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.

• Some accessories vanish while the HomeKit Bridge integration remains loaded.
• The issue appears after exposing a large room, domain, or group of entities.
• Home shows ‘No Response’ for a subset of accessories.
• Re-pairing temporarily restores devices but the problem returns.

Most likely causes

• Too many accessories or services are exposed through one bridge.
• Include/exclude filters changed after an entity rename.
• Unsupported or unusually complex entities create excessive services.
• The bridge’s pairing state and Apple Home cache no longer agree.
• Network isolation blocks mDNS between Home Assistant and Apple hubs.

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

1. Create a Home Assistant backup and capture the current HomeKit Bridge include/exclude configuration.
2. Count exposed entities and identify high-service devices such as multi-sensors, media players, or complex climate entities.
3. Temporarily narrow one bridge to a small, essential set using explicit includes.
4. Reload the integration and wait before making another change; Apple Home synchronization is not always immediate.
5. Confirm Home Assistant, the iPhone, and the active Apple home hub can exchange local mDNS traffic across VLANs.
6. If the smaller bridge is stable, divide devices logically across multiple bridges rather than placing everything on one.
7. Only as a final step, remove one confirmed broken bridge pairing and re-pair it using the new stable scope. Expect room assignments and automations to require review.

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 delete every bridge simultaneously.
• Do not expose entire domains when only a few entities are useful.
• Do not keep changing filters during Apple Home synchronization.

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

Should I use one bridge or several?

Several smaller, logically grouped bridges are often easier to diagnose and keep within practical accessory and service limits.

Will re-pairing preserve Apple Home rooms?

Not reliably. Treat re-pairing as a last resort and document room and automation assignments first.

Why do VLANs matter?

HomeKit discovery relies heavily on local multicast discovery, which routed or isolated networks may block.

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 HomeKit Bridge accessory loss problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.

1. Count accessories exposed through each bridge and record the filter configuration. Home Assistant’s official documentation notes a maximum of 150 unique accessories per bridge.
2. Identify whether missing items share a domain, room, integration, or recent rename. A filter mismatch often removes a group predictably rather than at random.
3. Record bridge names, pairing state, Apple home hub status, and the last configuration change. Avoid deleting pairings while collecting evidence because re-pairing can disturb room assignments.
4. Confirm Home Assistant, the phone, and the active Apple home hub can exchange local multicast discovery traffic. Guest Wi-Fi, VLAN isolation, or multicast filtering can break discovery.
5. Reduce one test bridge to a small explicit include list. This separates bridge-size and entity-complexity problems from general network failure.
6. Review unsupported or unusually complex entities. One physical Home Assistant device can expose multiple HomeKit services, so entity count alone may not describe bridge complexity.
7. Wait after reloading a bridge and make one change at a time. Apple Home synchronization and hub caching can make rapid edits appear inconsistent.
8. Document Apple Home automations and room assignments before any final re-pair, because removing and adding a bridge may require rebuilding organization.

Failure-pattern examples

• Accessory count approaches 150: split devices into logical bridges before adding more and keep explicit filters.
• Only renamed entities disappear: update include/exclude filters and reload the affected bridge, then allow synchronization time.
• Everything shows No Response after a network change: investigate mDNS routing, VLAN rules, Wi-Fi isolation, and active home-hub connectivity.
• A small test bridge works but the large bridge fails: reduce scope and separate complex domains rather than repeatedly re-pairing the same oversized bridge.
• One bridge is healthy and another is not: isolate configuration and pairing work to the failing bridge; do not delete every HomeKit integration.

Advanced notes that prevent false fixes

• The 150-accessory limit applies per bridge, and service complexity can create practical issues before the numeric limit.
• Explicit include lists are easier to audit than exposing entire domains by default.
• Cameras and other complex accessories may deserve separate planning because their requirements differ from simple switches.
• Network changes can mimic configuration failures; prove local discovery works before rebuilding pairings.
• Re-pairing is destructive to organization even when it fixes connectivity, so it belongs late in the decision tree.
• Maintain a bridge inventory containing purpose, included entities, approximate accessory count, pairing date, and responsible Apple home.

Final verification checklist

Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.

• Every intended accessory appears once.
• The bridge remains responsive through a home-hub change or normal restart.
• Accessory count stays below the documented limit.
• Room assignments and automations remain intact.
• No unintended entity domain is exposed.
• The result remains stable after synchronization time.

Official reference

Technical behavior and terminology were checked against Home Assistant HomeKit Bridge documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.

Related Troubliq guides

• ZHA device interview recovery
• MQTT availability troubleshooting
• HomeKit Bridge accessory recovery

An MQTT entity that changes from available to unavailable every few minutes may still publish sensor values correctly. The useful clue is the availability topic: Home Assistant is reporting what it receives, not guessing whether the physical device is healthy.

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.

• State values update, but the device badge repeatedly becomes unavailable.
• The problem begins after broker, router, or Home Assistant restarts.
• Several devices fail together, or only one firmware family is affected.
• The log shows reconnects, socket errors, or duplicate client identifiers.

Most likely causes

• A retained offline payload remains on the availability topic.
• The device uses a short keepalive and unstable Wi-Fi.
• Two clients share the same MQTT client ID and disconnect each other.
• Birth and Last Will payloads do not match Home Assistant’s expected values.
• The broker, add-on, or device clock restarts on a repeating schedule.

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

1. Open the MQTT integration and listen to the exact availability topic; record payloads and timestamps without publishing anything.
2. Compare the entity’s configured payload_available and payload_not_available values, including capitalization and whitespace.
3. Check whether the offline message is retained. A stale retained Last Will can survive restarts.
4. Inspect the broker log for repeated connections using the same client ID.
5. Give every physical device a unique client ID, then restart only the affected client.
6. Check Wi-Fi signal, DHCP stability, power supply, and keepalive settings on the device.
7. If multiple devices fail simultaneously, investigate broker or network infrastructure before editing every device.
8. After correcting the publisher, clear or replace only the known stale retained availability message using the device’s documented procedure.

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 publish a blank retained payload to broad wildcard topics.
• Do not disable availability reporting just to hide a real disconnect.
• Do not expose the broker to the public internet while troubleshooting.

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

Can sensor values update while availability is wrong?

Yes. State and availability often use different topics and retained-message behavior.

What does a duplicate client ID do?

Most brokers disconnect the older session when another client connects with the same identifier, creating a repeating online/offline cycle.

Should I delete the MQTT integration?

Usually not. First isolate the exact topic, payload, client ID, and timestamp pattern.

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 MQTT availability problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.

1. Capture the exact availability topic and every payload over a complete online-offline cycle. Include timestamps, retain flags when available, and client connection events from the broker log.
2. Compare the observed strings byte-for-byte with payload_available and payload_not_available. Capitalization, whitespace, encoding, and JSON structure matter; visually similar payloads may not match.
3. Determine whether the entity uses one availability topic or a list. Home Assistant supports availability modes such as all, any, and latest, and the selected mode changes how multiple topics are evaluated.
4. Inspect broker logs for duplicate client identifiers. MQTT brokers commonly replace an existing connection when a second client connects with the same ID, producing a repeating disconnect pattern.
5. Check the device’s Last Will, birth message, retain setting, keepalive, and clean-session behavior. Availability faults often survive restarts because a retained offline payload remains valid at the broker.
6. Correlate failures across devices. Simultaneous changes point toward broker, network, power, DNS, or host problems; one device family points toward its firmware or configuration.
7. Measure Wi-Fi signal and power stability at the device, but do not stop there. A strong signal does not rule out DHCP conflicts, access-point roaming, brownouts, or duplicate credentials.
8. Before clearing a retained message, verify the exact topic and understand the publishing tool. A wildcard or wrong topic can disturb many devices.

Failure-pattern examples

• State updates continue while availability is offline: troubleshoot the availability topic and payload separately from the state topic.
• All MQTT devices go unavailable after a broker restart: inspect retained birth/Last Will behavior and reconnection logs before editing every entity.
• One device flips at a fixed interval: compare keepalive, watchdog, DHCP lease, power-save, and scheduled restart timing.
• Two identical devices knock each other offline: assign unique MQTT client IDs and confirm both remain connected simultaneously.
• Multiple availability topics use mode all: one silent auxiliary topic can hold the entity offline even though the primary device is publishing normally.

Advanced notes that prevent false fixes

• Retained messages describe the last retained value, not necessarily the present physical state; publishers must update them correctly.
• QoS affects delivery guarantees but does not repair a semantically wrong availability payload.
• Disabling availability hides the diagnostic signal and should not substitute for fixing reconnections.
• Do not expose an MQTT broker publicly or weaken authentication during troubleshooting.
• Use a narrow topic listener and redact usernames, passwords, tokens, and personally identifying topic components.
• After repair, document topic names, expected payloads, client ID, retain behavior, and broker location.

Final verification checklist

Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.

• The client remains connected longer than the previous failure interval.
• Availability and state topics show expected payloads.
• No duplicate-client disconnect appears in broker logs.
• The entity recovers correctly after one controlled broker restart.
• Other MQTT devices remain unaffected.
• No stale retained offline value reappears.

Official reference

Technical behavior and terminology were checked against Home Assistant MQTT documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.

Related Troubliq guides

• ZHA device interview recovery
• duplicate ESPHome device cleanup
• HomeKit Bridge accessory recovery

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

1. Open both device pages and record the integration entry, IP address, last-updated behavior, and entity IDs.
2. Trigger a harmless physical change such as toggling an onboard LED or watching a sensor update; identify the entry receiving fresh state.
3. Open automations, scripts, dashboards, and scenes that use the stale entity IDs and move them to the live entities before removal.
4. Create a backup and export or copy the working ESPHome YAML.
5. Remove only the unavailable integration entry from Settings → Devices & services. Do not delete the working node from the ESPHome dashboard.
6. Restart Home Assistant once and allow discovery to settle.
7. If the duplicate returns, compare the node name, API encryption key, static IP, and manual integration host. Keep one consistent discovery method.
8. 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.

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.

Related Troubliq guides

• ZHA device interview recovery
• duplicate ESPHome device cleanup
• MQTT availability troubleshooting

A Zigbee device that appears in ZHA, reaches most of the interview, and then fails is not the same problem as a device that never enters pairing mode. The radio has usually heard the device; the failure happens while Home Assistant requests endpoints, clusters, or basic attributes. That distinction prevents unnecessary coordinator resets.

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.

• The device is discovered but remains partially configured or marked unavailable.
• The interview repeatedly stalls near completion.
• A battery device pairs only when held beside the coordinator.
• The same device worked before a battery change, migration, or factory reset.

Most likely causes

• The sleepy device stopped responding before the interview finished.
• The device still remembers an earlier Zigbee network.
• Weak signal or 2.4 GHz interference interrupted cluster discovery.
• The coordinator or router is busy after a restart.
• A manufacturer-specific quirk needs a fresh interview or newer device support.

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

1. Create a Home Assistant backup before changing the Zigbee network.
2. Replace or fully charge the device battery; low voltage can allow pairing but fail sustained communication.
3. Factory-reset the device using its manufacturer procedure, then keep it awake throughout the interview by tapping its pairing button every few seconds.
4. Pair within a few feet of a powered Zigbee router or the coordinator, but keep USB coordinators away from USB 3 cables, hubs, Wi-Fi access points, and metal enclosures.
5. In ZHA, remove only the failed device entry—not the coordinator—then start Add Device and retry once.
6. If it still fails, restart Home Assistant once, wait for the Zigbee network to settle, and review Settings → System → Logs for ZHA, zigpy, endpoint, timeout, or unsupported-cluster messages.
7. Test another known-good device. If only one model fails, treat it as device-specific rather than rebuilding the network.

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 delete the ZHA integration or erase the coordinator as a first step.
• Do not repeatedly power-cycle the coordinator during an interview.
• Do not assume a high percentage means the device is almost healthy; one missing endpoint can prevent usable configuration.

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

Should I re-pair every Zigbee device?

No. A single interview failure rarely justifies rebuilding a working mesh.

Can Wi-Fi cause this?

Yes. Zigbee and 2.4 GHz Wi-Fi share spectrum, and proximity to access points or USB 3 equipment can make an intermittent failure look like a software bug.

When should I check device support?

After a clean reset, strong-signal pairing, and a second controlled attempt still fail for the same model.

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 ZHA interview problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.

1. Record the device manufacturer, model, mains-or-battery status, pairing distance, and the exact stage where the interview stops. These details distinguish a sleepy end-device problem from a coordinator-wide problem.
2. Open the device page and note which entities, endpoints, and diagnostic values were created. A partially created device proves that discovery occurred even if cluster interrogation did not finish.
3. Compare the failure with a known-good Zigbee device paired from the same location. If the second device also struggles, investigate radio placement, interference, and coordinator health before blaming one product.
4. For battery devices, keep the unit awake throughout pairing according to its manual. Many devices sleep quickly after joining, which can interrupt the exchange of endpoint and attribute information.
5. Check the Home Assistant log at the exact pairing time. Preserve the manufacturer, model, IEEE address suffix, exception name, and retry sequence while removing credentials before sharing a report.
6. Inspect whether the device was previously joined to another coordinator. A proper factory reset is model-specific; merely removing a battery often does not erase the former network.
7. Move a USB coordinator away from USB 3 equipment and metal using a quality extension cable. Change only placement first; channel changes can require wider planning and should not be casual experiments.
8. After a failed attempt, remove only the incomplete device, restart nothing unless logs indicate a stuck integration, and allow the mesh to settle before one controlled retry.

Failure-pattern examples

• Fails only with one battery sensor: replace the battery, perform the documented factory reset, pair close to a stable router or coordinator, and keep the sensor awake. Do not rebuild ZHA.
• Several new devices fail from every room: test radio placement, host load, coordinator connectivity, and interference. Preserve the network database and investigate shared infrastructure.
• Device joins and controls work but some entities are missing: allow time for initialization, check disabled entities, confirm model support, and collect signatures before considering a device handler issue.
• Pairing works beside the coordinator but not at installation location: the join succeeded; the mesh path is the likely weakness. Add or reposition appropriate powered routers rather than repeatedly pairing.
• Failure began after a host migration: confirm the correct serial device path, coordinator type, extension cable, and restored Zigbee data before changing device firmware.

Advanced notes that prevent false fixes

• Treat a high interview percentage as a progress indicator, not proof that the remaining step is unimportant.
• Avoid channel changes unless interference evidence supports them and you understand how every device will be affected.
• A custom quirk should be considered only after obtaining the complete device signature and checking existing support.
• Battery voltage reported by a device can lag; a fresh known-good battery is a stronger test than one stale percentage reading.
• Powered Zigbee routers must be compatible and placed where they provide a useful route, not clustered beside the coordinator.
• When reporting a bug, include reproducible steps, ZHA diagnostics, logs, coordinator model and firmware, Home Assistant version, and device signature.

Final verification checklist

Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.

• Device remains available after the normal sleep interval.
• All expected endpoints and entities appear or unsupported ones are documented.
• A control or sensor update succeeds from the final installation location.
• The log contains no repeating interview retries.
• The test survives one normal Home Assistant restart.
• No unrelated Zigbee devices became unstable.

Official reference

Technical behavior and terminology were checked against Home Assistant ZHA documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.

Related Troubliq guides

• ZHA device interview recovery
• duplicate ESPHome device cleanup
• MQTT availability troubleshooting