Category: Hubs & Automations

Troubleshooting for hubs, bridges, scenes, and cross-platform automations. Identify which controller owns each device, distinguish entity failures from automation failures, preserve pairing records, and change one integration at a time. Use the Troubliq diagnostic method before removing a hub or bridge.

UniFi Protect unavailable in Home Assistant: authentication, API mode, streams, and NvrError fixes

Direct answer: When UniFi Protect is unavailable in Home Assistant, start by confirming that Protect is running on a supported UniFi OS Console, that the console is reachable by its local IP address, and that Protect is on the Stable release channel at version 7.2.105 or later. Then verify the connection mode: full access requires both a local-only UniFi OS user and an API key, while API-key-only mode intentionally exposes fewer entity types and no media source, actions, or proxy views. Do not delete the integration, rotate every credential, or reset cameras until you have identified whether the failure is authentication, permissions, routing, stream availability, or an unsupported Protect installation.

Symptoms and exact scope

This guide covers the official Home Assistant UniFi Protect integration connected to Protect running on a UniFi OS Console. It does not cover self-hosted or containerized Protect installations, which Ubiquiti does not officially offer and Home Assistant does not support. Common symptoms include the entire integration showing unavailable, cameras appearing without live video, only camera and light entities being present, event or sensor entities disappearing, media browser folders missing, repeated authentication failures, delayed video, and log messages containing NvrError with 404 - Reason: Not Found or 502 - Reason: Bad Gateway.

Record the Home Assistant version, UniFi OS version, Protect version, console model, camera models, connection mode, console IP address, and the time the problem began. If the failure followed an upgrade, record whether the console was on Stable, Release Candidate, or Early Access. This information separates an ordinary configuration problem from an unsupported release-channel regression.

Before changing anything

Confirm that recordings and live views work inside the local UniFi Protect application. If Protect itself cannot display cameras, Home Assistant is downstream of the real failure. Check storage warnings, console utilization, camera adoption status, and whether Protect is still starting. Avoid rebooting the console during an active firmware update or while storage repair is in progress.

Safety and privacy: Camera feeds, event thumbnails, doorbell images, fingerprints, NFC identifiers, access logs, local IP addresses, API keys, and usernames are sensitive. Never paste an API key or an unredacted diagnostics archive into a public forum. Do not expose the UniFi console directly to the internet to make Home Assistant connect. Use local routing or a properly secured remote-access design instead.

UniFi Protect failure matrix

Observation	Most likely layer	Least-destructive next check
All Protect entities unavailable	Console reachability, authentication, Protect service, or version	Open the local console IP and confirm Protect is running
Camera streams work but sensors and events are missing	API-key-only mode or limited permissions	Check the configured connection mode and user role
Media source and notification proxy URLs are missing	API-key-only mode	Reconfigure to full access if those features are required
Live feed repeatedly refreshes snapshots	No active RTSPS stream	Check the Home Assistant repair and Protect stream availability
`404 - Reason: Not Found`	Stale endpoint, Protect restart, proxy path, or API mismatch	Confirm current stable versions and reload once after Protect is fully online
`502 - Reason: Bad Gateway`	Protect backend or proxy unavailable	Test Protect locally and inspect console health before changing Home Assistant
Alarm Manager entities disappeared	Protect Alarm Manager switched to Global mode	Check whether sensors, relays, fobs, or an Alarm Hub were adopted
Only some cameras or controls are missing	User permissions, device capability, or API-version support	Compare the local user role and camera capabilities

1. Confirm supported hardware and software

The official integration supports UniFi Protect only when it runs on a UniFi OS Console capable of running Protect. A container or third-party self-hosted installation may report an internal address in camera-stream URLs that Home Assistant cannot reach. That symptom cannot be repaired reliably by changing Home Assistant host fields because the unsupported Protect instance is advertising unusable endpoints.

Home Assistant currently requires UniFi Protect 7.2.105 or later. Update an older installation through the supported UniFi OS interface, but do not move to Early Access or Release Candidate merely to obtain a newer number. Home Assistant explicitly does not support those prerelease channels, and they can change the API before the integration is ready.

If a feature is absent rather than the whole integration failing, check whether the feature requires a newer Protect public API version. A camera can remain available while a recently added entity is missing. That is different from authentication failure and should not trigger credential resets.

2. Test the console locally

From the same trusted network as Home Assistant, open the console by its local IP address. Confirm that UniFi OS loads, Protect opens, cameras are adopted, and a live view plays. This tests the route without depending on the cloud portal. If only unifi.ui.com works, investigate local DNS, VLAN routing, firewall policy, or console networking.

Compare the address stored in Home Assistant with the console’s current address. Reserve the console IP in the router rather than assigning an arbitrary static address inside the DHCP pool. If the address changed, use the integration’s Reconfigure flow instead of deleting the integration. Preserving the entry protects entity IDs used by automations and dashboards.

If Home Assistant and the console are separated by VLANs, verify narrowly scoped local access. Do not open broad inbound internet rules. Record existing firewall rules before testing and restore them if a change does not help. A temporary same-subnet test can prove whether routing is the failing layer without permanently weakening segmentation.

3. Understand full access versus API-key-only mode

Full access is the recommended mode for most users. It requires a local-only UniFi OS user plus an API key. It provides the broad entity set, actions, media source, and proxy views used for notification thumbnails and video clips. API-key-only mode is intentionally limited: cameras provide streams and snapshots, lights are supported, and some NVR Alarm Manager functionality is available, but binary sensors, events, media players, many controls, actions, media source, and proxy views are not.

If a reconfiguration from full access to API-key-only caused entities to become unavailable, that is expected behavior, not data corruption. Switch back through Settings → Devices & services → UniFi Protect → Reconfigure if those entities are needed. They should return when the required mode and permissions are restored.

Do not create overlapping integration entries for each connection mode. Duplicate entries can create confusing device and entity sets without solving the underlying permission difference.

4. Verify the local user correctly

For full access, the account must be created in the console’s local portal, not as a Ubiquiti cloud SSO user. Open the console by IP, go to Admins & Users, add an administrator restricted to local access, and assign the Protect role appropriate to the functions Home Assistant needs. The official documentation recommends Full Management for the widest support, but a narrower role can be used if you accept fewer or read-only entities.

A cloud account that works at unifi.ui.com does not satisfy this local-user requirement. Repeated login failures with a valid cloud password often point to the wrong account type rather than a bad password.

After changing permissions, reconfigure or reload the existing integration. Verify that the expected entity domains return before changing anything else. If only one camera remains absent, inspect device-specific access and adoption rather than increasing the global role again.

5. Validate the API key without exposing it

Create the API key from Protect’s Integrations page while logged into the local portal as an administrator. Copy it once into the Home Assistant setup flow. Do not save it in screenshots, notes synchronized to public services, YAML examples, or support posts.

If the key was revoked or rotated, reconfigure the existing integration with the replacement. Avoid deleting the entry because deletion can break dashboards, notification automations, and entity references. If compromise is suspected, revoke the old key after the replacement is confirmed, then review console access logs and Home Assistant diagnostics.

An API key alone does not grant full-access features. If the entry was configured in full-access mode, both the local username/password and API key must be valid.

6. Diagnose missing or delayed camera streams

Home Assistant uses active RTSPS streams exposed by the Protect public API and selects the highest-quality active stream as the default feed. If no stream is active, Home Assistant may create a repair that can enable one. Until a stream exists, the camera feed can fall back to repeatedly refreshed snapshots, increasing console load and looking like a slow video connection.

Open the camera in Protect and verify that it is online and streaming. Check Home Assistant Repairs for a stream-related item. Enable the required stream through the supported repair rather than copying obsolete RTSP URLs from old tutorials. Then reload the integration and test a single camera before changing all cameras.

Video delay can also reflect transcoding, browser playback, network loss, or an overloaded console. Compare a local Protect live view with Home Assistant. If both are delayed, focus on the camera, console, storage, or network. If only Home Assistant is delayed, collect integration diagnostics and note the stream quality and client used.

7. Interpret NvrError 404 and 502 safely

A 404 - Reason: Not Found means a requested Protect resource or endpoint was not found. It can occur temporarily while Protect restarts, after an API path changes, or when a saved reference points to an event that no longer exists. A 502 - Reason: Bad Gateway indicates that the gateway could not obtain a valid response from the Protect backend. Neither message proves that the camera itself is defective.

First verify that Protect is fully loaded locally. Wait for an intentional console or Protect restart to finish, then reload the integration once. Confirm Stable-channel versions and capture the exact log time, endpoint category, and affected camera. Do not loop reloads or console reboots; repeated reconnects can obscure the original failure and add load.

If the error persists while Protect works locally, download Home Assistant diagnostics, redact secrets and local identifiers, and check the official integration issue tracker for the same Protect and Home Assistant versions. A concise report should include console model, Protect version, Home Assistant version, camera model, connection mode, exact error, reproduction steps, and whether local Protect playback works.

8. Explain entities that disappear by design

Some missing entities are expected consequences of settings. Smart-sensor functions that are disabled are marked unavailable. Alarm Manager and Alarm profile entities appear only when Protect Alarm Manager is in Local mode. Adopting sensors, relays, fobs, or an Alarm Hub can switch Alarm Manager to Global mode, where the public API does not expose arm profiles and Home Assistant cannot create those entities.

Likewise, G3 cameras do not provide the smart detections documented for G4 and AI series cameras. Package detection is represented as an event entity rather than a sustained binary sensor. These capability differences should be checked before treating a missing entity as a regression.

9. Verify recovery

The UniFi OS console opens through its local IP from the Home Assistant network.
Protect is on Stable version 7.2.105 or later and finishes loading normally.
The integration uses the intended full-access or API-key-only mode.
Full access uses a local-only user, not a cloud SSO account, plus a valid API key.
Expected cameras and supported sensors appear without duplicate integration entries.
An active RTSPS stream plays for one camera without snapshot-only fallback.
Media source, proxy views, actions, and events appear only when the selected mode supports them.
Logs remain free of recurring 404 or 502 NvrErrors after one normal reload.

Rollback and recovery

If a new API key fails, restore the previous working key if it has not been revoked. If changing to API-key-only removes needed entities, reconfigure to full access. If a VLAN test fails, restore the original firewall rules and network placement. If a Protect update caused the failure, do not attempt unsupported firmware downgrades without Ubiquiti guidance; preserve recordings and configuration, collect diagnostics, and wait for a supported stable fix.

If the integration entry was deleted, recreate it with the same console and credentials, then repair automation references carefully. Restoring an entire Home Assistant backup is usually excessive for a credential or routing issue and may roll back unrelated changes.

Prevention

Reserve the console’s local IP address.
Use a dedicated local-only account and a dedicated API key for Home Assistant.
Keep Protect and UniFi OS on Stable channels.
Record the console, Protect, Home Assistant, and camera versions before upgrades.
Export or verify backups before major console changes.
Review entity availability after changing connection mode, user role, Alarm Manager mode, or adopted security devices.
Keep API keys, event images, access logs, and diagnostics private.

Related Troubliq guides

Use the Device Unavailable Diagnostic when the failing network layer is unclear. The Smart-Home Diagnostic Decision Tree can separate authentication, routing, and device problems. For another camera integration workflow, compare the Reolink camera unavailable guide. If a reverse proxy produces an HTTP error before Home Assistant loads, use the Home Assistant 400 Bad Request reverse-proxy guide.

Sources and review record

Last reviewed: September 27, 2026. Testing disclosure: Troubliq synthesized current official documentation and documented integration behavior. We did not claim hands-on testing with every UniFi OS Console, camera model, firmware version, network design, or Protect release.

September 27, 2026

Samsung TV not authorized in Home Assistant: permissions, token, network, and Wake-on-LAN fixes

Direct answer: If a Samsung TV is unavailable in Home Assistant or will not turn on, first confirm that the television is supported, connected to the same subnet as Home Assistant, and reachable at its current IP address. For power-on failures, verify that Home Assistant knows the TV’s MAC address and that network standby or Wake on LAN is enabled on the television. Do not delete the integration or factory-reset the TV until you have separated an IP, permission, VLAN, and wake-up problem.

This guide applies primarily to Samsung Smart TVs with Tizen from 2016 onward and models that expose the REST and WebSocket interfaces used by Home Assistant. Older H- and J-series televisions can use a different encrypted pairing flow, so their behavior may not match a newer Tizen model.

Symptoms and scope

The Samsung TV entity shows Unavailable even though the television is powered on.
Home Assistant can turn the TV off but cannot turn it on.
The TV asks for permission every time Home Assistant connects.
The entity works briefly and becomes unavailable after the router assigns a new address.
Discovery fails when the TV and Home Assistant are on different VLANs.
Volume, source or remote commands fail while basic power state still updates.
An automation calls media_player.turn_on, but nothing happens.

Before making changes

Record the exact TV model, model year, firmware version, current IP address, wired or wireless connection, MAC address and Home Assistant version. In Home Assistant, open Settings → Devices & services → Samsung Smart TV and download diagnostics if the integration provides that option. Note the entity ID before removing or renaming anything because dashboards and automations may depend on it.

Safety and privacy: Do not open the television or power supply. Disconnecting a wall-mounted TV can create a fall or electrical hazard. Do not publish a full diagnostic file without reviewing it for local IP addresses, MAC addresses, device names or tokens. Avoid exposing the TV’s control ports to the public internet.

Fast diagnostic matrix

Observation	Likely layer	Safest next step
TV is unavailable while powered on	IP, subnet, permission or WebSocket connection	Compare the router’s current IP with the integration host
TV turns off but not on	Wake on LAN or network standby	Verify the MAC address and wake settings
TV asks for permission repeatedly	Samsung Device Connection Manager	Set access notification to First time only
Failure began after moving the TV to an IoT VLAN	Known subnet limitation	Test TV and Home Assistant on the same subnet
Remote commands fail on an older H/J model	Legacy encrypted pairing	Complete the TV’s pairing prompt and preserve the entry
State works but a specific key does not	Model-specific command support	Test a documented basic command before changing the integration

1. Confirm the television itself is online

Start with checks that do not alter configuration. Turn the TV on with its physical remote. Confirm that a built-in streaming app can reach the network and that the router lists the TV as a connected client. If the TV is absent from the router, Home Assistant cannot repair the underlying network connection.

For Wi-Fi, check that the TV joined the intended network rather than a guest SSID. Guest networks commonly isolate clients from one another. For Ethernet, confirm link lights on the switch or router and inspect the cable without moving a wall mount unsafely. Restarting the TV is reasonable only after you have recorded its current address and the affected appliance can safely lose power.

If the router shows the TV online, note its IP and MAC address. Do not rely on an address written down months ago. DHCP leases change after router replacements, long power outages or network redesigns.

2. Check model and protocol compatibility

The official Samsung Smart TV integration documents support for Tizen televisions from 2016 onward and models with WebSocket and REST capabilities. A “smart TV” label alone is not enough because Samsung used different control protocols across generations.

If the model is from the H or J series, Home Assistant may detect an encrypted protocol and start a manual pairing flow. Complete the permission prompt shown by the TV rather than repeatedly deleting and adding the integration. If the model predates the documented interfaces, partial discovery does not guarantee reliable control.

Before blaming a Home Assistant update, compare the model and firmware with the current official integration documentation and known issues. Do not install an unrelated custom component simply because it supports a similarly named model; running two integrations against the same TV can create duplicate entities and confusing connection attempts.

3. Repair an incorrect IP address safely

Compare the host stored in the Samsung integration with the router’s current client entry. If the addresses differ, use the integration’s Reconfigure option when available or update the entry through the supported setup flow. Preserve the existing entity whenever possible so automations and dashboards continue to reference the same object.

After a successful connection, create a DHCP reservation in the router for the TV’s MAC address. A reservation keeps address management centralized and avoids selecting an address already assigned to another device. Do not choose an arbitrary static IP inside the router’s dynamic pool.

Verify this layer while the TV is on. The media-player state should update, and a low-risk volume or mute command should work. If the entity still fails while the IP is correct, continue to permissions and subnet checks instead of cycling through random addresses.

4. Fix repeated Samsung permission prompts

Newer Samsung TVs can be configured to ask for permission on every connection attempt. That can make Home Assistant appear unreliable because reconnects wait for someone to approve the television prompt.

On the TV, open Device Connection Manager → Access Notification and change the setting to First time only. Then open the device list in the same manager and remove stale or duplicated Home Assistant attempts. Reconnect once and approve the fresh request.

Menus differ slightly by model and firmware. Do not change unrelated privacy or advertising settings just to locate this option. If the TV provides only Allow and Deny entries, remove the old Home Assistant record and allow the next connection once.

Verify by turning the television off and on normally, waiting for the integration to reconnect, and checking that no new permission prompt appears. A single successful command without a reconnect is not enough to prove this issue is resolved.

5. Diagnose VLAN and subnet failures

The official integration documents a significant limitation: Samsung televisions may refuse WebSocket connections across different subnets or VLANs. A firewall rule that allows the port does not necessarily overcome a restriction enforced by the television itself.

Test this cleanly by placing Home Assistant and the TV on the same subnet temporarily. If the integration connects there, the TV, credentials and basic integration are working. The failure is in the network boundary or the television’s same-subnet restriction.

Do not respond by opening the entire IoT VLAN to the trusted network. Some networks can use a carefully designed proxy or IP masquerading rule, but that is router-specific and should be implemented only if you understand the security effect. The safest general solution is often to keep the TV and Home Assistant interface that controls it on a compatible local segment while restricting unrelated IoT traffic.

Document the original VLANs and firewall rules before testing. Restore them if the experiment does not improve the connection.

6. Fix “turn off works, turn on does not”

Turning a television off uses an active connection. Turning it on is different because the TV’s normal control interface is asleep. Home Assistant therefore needs a wake mechanism.

If the integration learned the TV’s MAC address during discovery, it can attempt Wake on LAN when the Turn on action is called. Check that network standby, power-on with mobile, IP remote, or Wake on LAN is enabled in the TV’s network or power settings. Samsung changes the wording between firmware versions.

Wireless wake support varies by model. A television may disconnect Wi-Fi completely during deep standby even though Ethernet wake works. Test with the existing connection first; do not purchase adapters or run new cabling before confirming the model’s documented capability.

If Home Assistant did not learn the MAC address, add the official Wake on LAN integration and create a controlled automation using the Samsung TV’s samsungtv.turn_on trigger and wake_on_lan.send_magic_packet action. Use the MAC address from the router or TV network page rather than guessing it.

wake_on_lan:

automation:
  - alias: "Wake Samsung TV"
    triggers:
      - trigger: samsungtv.turn_on
        entity_id: media_player.samsung_smart_tv
    actions:
      - action: wake_on_lan.send_magic_packet
        data:
          mac: "AA:BB:CC:DD:EE:FF"

Replace the sample values with your own entity and MAC address. Do not publish the real MAC in a public support post. If broadcasts do not cross VLANs, configure the broadcast address only after confirming the router’s behavior and the Home Assistant documentation.

7. Interpret Wake on LAN results

A magic packet action only proves that Home Assistant sent a packet; it does not prove the TV received it or powered on. Watch the router client list and the television’s status LED. If the TV appears on the network several seconds later, the wake path worked even if the media-player entity needs more time to reconnect.

If Ethernet wake works but Wi-Fi wake fails, the difference points to standby behavior rather than the integration. If neither works, confirm the MAC, wake setting and broadcast path. If the TV wakes from Samsung’s mobile app while away from home but not from a local magic packet, the app may be using a vendor cloud path that is different from Wake on LAN.

Do not compensate with a smart plug unless the television manufacturer explicitly permits hard power interruption. Repeatedly removing mains power can corrupt settings and is not equivalent to a normal standby wake.

8. Test remote commands and sources logically

Once availability and power are stable, test one basic command such as volume up, mute or Home. Supported key codes vary by model. A failure of one application or source shortcut does not mean the entire integration is offline.

Test commands individually before creating a sequence. Long sequences can run too quickly or behave differently depending on which screen is active. Add delays only after confirming every individual command is supported. Avoid factory or service-menu key codes; they can change calibration or other sensitive settings.

For source selection, inspect the source list exposed by the media-player entity. Some models expose only TV and HDMI, while others expose applications. Do not hard-code a source name that the entity does not currently report.

9. Capture useful diagnostics

Enable debug logging from the integration menu, reproduce the failure once, then disable logging and download the file. Record whether the TV was awake, its connection type, subnet relationship, and whether the permission prompt appeared.

Before sharing diagnostics, remove local addresses, MAC addresses, names and tokens. A useful issue report includes the exact model, model year, firmware, Home Assistant version, connection type, error time, steps already tested and whether same-subnet testing changed the result.

Verification checklist

The TV is visible in the router at the reserved IP.
The model is within the integration’s supported protocol range.
The TV and Home Assistant can establish a connection on the same subnet.
The Device Connection Manager trusts Home Assistant without prompting repeatedly.
A basic command works while the TV is on.
The TV wakes from a known-good magic packet or documented native wake method.
The media-player entity reconnects after wake and stays available through multiple cycles.
Debug logging is disabled after testing.

Rollback and recovery

If a VLAN experiment fails, restore the original network assignment and firewall rules. If a new Wake on LAN automation causes repeated wake attempts, disable the automation and keep the Samsung integration itself. If you removed stale permission records, approve the next legitimate Home Assistant request once.

If the integration was deleted, restore from a recent Home Assistant backup only when rebuilding the entity relationships would be more disruptive than the restore. A simple IP or permission error normally does not justify rolling back the whole system.

Prevention

Reserve the television’s IP address in the router.
Keep the model, firmware, IP and MAC recorded privately.
Test network segmentation changes with the TV before making them permanent.
Use First time only for connection notifications when available.
Keep power-on logic separate from normal media-control automations.
Review Home Assistant and Samsung firmware release notes before major upgrades.
Avoid duplicate custom integrations controlling the same TV.

Related Troubliq guides

Start with the Smart-Home Diagnostic Decision Tree when the failing layer is unclear. Use the Device Unavailable Diagnostic for a broader network-first workflow. For another IP-change example, see WLED unavailable after an IP change. If VLAN routing is suspected across several products, compare the network isolation checks in Shelly unavailable in Home Assistant.

Evidence, applicability, and safe verification

Applies to: the Home Assistant Samsung Smart TV integration and Samsung TVs that expose the required local-network control interface. Menu names differ by model and firmware.
Exact symptom covered: “Home Assistant is not authorized to connect to this Samsung TV. Check your TV’s External Device Manager settings to authorize Home Assistant,” plus unavailable entities and failed power-on attempts.
Least-destructive check: keep the TV on, confirm Home Assistant and the TV can reach each other locally, then approve the on-screen connection request in the TV’s External Device Manager before deleting tokens or re-adding the integration.
Expected result: the TV accepts the authorization request, Home Assistant stores a usable token where the model supports it, and a basic command works while the TV is awake. Wake-on-LAN is a separate path and may still require the correct MAC address and network broadcast handling.
Verification: reload the integration once, confirm the entity remains available, and test one reversible command such as mute or volume. Do not use a source-launch failure alone as proof that authorization failed.
Rollback: if a change worsens control, restore the previous IP reservation, VLAN/firewall rule, or MAC setting. Removing the integration should be a last resort because it can discard a working token and entity references.
Privacy and safety: do not publish TV tokens, MAC addresses, internal IPs, network captures, or diagnostic downloads without redaction. Avoid broad firewall rules; allow only the minimum local traffic required.
Testing disclosure: this guide is based on current official Home Assistant documentation and conservative network diagnostics. Troubliq did not physically test every Samsung model, firmware, router, or VLAN design.
Last reviewed: September 30, 2026.

Sources and review record

Last reviewed: September 21, 2026. Testing disclosure: Troubliq synthesized current official documentation and documented integration behavior. We did not claim hands-on testing with every Samsung model, firmware version or network design.

September 21, 2026

SwitchBot device not discovered in Home Assistant: Bluetooth and passive-mode diagnosis

Direct answer: A SwitchBot Hub is not required for Home Assistant’s SwitchBot Bluetooth integration. If a device is missing, verify working Bluetooth coverage and check whether the Home Assistant Bluetooth adapter is in Active or Passive mode. Active mode supports local discovery; Passive mode requires synchronizing nearby devices through the SwitchBot account. Trigger pairing advertisements safely, confirm the device is not connected to another app, and use account import for encrypted-device keys when required.

Last reviewed: September 15, 2026. Applies to current Home Assistant installations using the official integration named below; menus can vary slightly by release and installation type.

Symptoms and scope

The device may never appear in discovered integrations, appear only intermittently, expose sensors but not controls, or remain unavailable after moving Home Assistant. Multiple identical models can also be confused if their Bluetooth addresses were not recorded. Discovery failure is not proof that a cloud hub is required.

Prerequisites and evidence to preserve

Identify the exact model, firmware, Bluetooth address when available, distance and obstructions to the nearest Home Assistant Bluetooth adapter or proxy, and whether the device is already linked to a SwitchBot account. Confirm Home Assistant’s Bluetooth integration itself is healthy before diagnosing one product.

Likely causes

1. No working Bluetooth adapter or proxy can hear the device reliably.

2. The device is not advertising until a button press or power cycle.

3. Home Assistant’s Bluetooth adapter is configured in Passive mode, which requires SwitchBot account synchronization instead of local discovery.

4. Encrypted device data requires a key imported from the account or entered securely.

5. The device is connected to another app, or two same-model devices were confused because their Bluetooth addresses were not verified.

Least-destructive diagnostic sequence

Step 1: Open the Bluetooth integration and verify at least one active adapter or proxy. Confirm other nearby Bluetooth devices are being received. If all Bluetooth devices disappeared together, repair the shared adapter path first.

Step 2: Move temporarily within reasonable range without permanently relocating equipment. Bluetooth uses low power and walls, metal enclosures, appliances, and USB interference can matter. A brief close-range discovery test distinguishes coverage from configuration.

Step 3: For devices with a physical button, follow the documented hold action to enter pairing mode. For devices without a button, power-cycle once to trigger advertising. Avoid repeated resets; advertising and factory reset are different operations.

Step 4: Wait through a realistic discovery interval and check discovered integrations. Record the Bluetooth address so identical devices can be distinguished. Do not add whichever same-model entry appears first without verification.

Step 5: Check the Bluetooth adapter’s Add mode. In Active mode, devices are normally discovered locally; if one remains missing, verify it is powered, in range, and not connected to another app. In Passive mode, local scanning cannot add devices directly, so synchronize nearby devices through the SwitchBot account.

Step 6: For encrypted models, use the supported account-import method where possible, or enter the key ID and encryption key only in Home Assistant’s secure setup interface. Never paste encryption keys into forums, screenshots, or chat.

Step 7: If using account synchronization, understand that SSO accounts such as Login with Google are not supported by the integration’s username-and-password flow according to the documentation. Do not weaken account security or reuse passwords to work around that limitation.

Step 8: After addition, verify several state updates and one safe command if the device supports control. Then move back to the intended location and confirm the signal path remains reliable.

Diagnostic asset: choose the next branch

Discovery decision tree: no Bluetooth devices visible means repair the adapter or proxy; an Active-mode adapter with only this device missing means trigger advertising, confirm support, and disconnect other apps; a Passive-mode adapter means synchronize the SwitchBot account; encrypted data without usable entities means import the correct key securely; discovery only at close range means improve Bluetooth proxy placement rather than resetting.

Deeper checks when the first sequence does not solve it

Begin with observation rather than removal. In Settings, Devices & services, open the integration entry and compare the integration status with individual entity states. Write down exactly what is unavailable, what remains responsive, and when the change began. This boundary prevents a narrow entity problem from being treated as a complete integration failure.

Check Settings, System, Repairs before changing configuration. A repair notice can describe a migration, deprecated behavior, reauthentication requirement, or duplicate-device correction more accurately than a generic entity state. Read the notice fully and record its wording before dismissing or applying it.

Use the device’s own local controls or official app as a comparison, but interpret that test carefully. A working vendor app may use a cloud path while Home Assistant uses the local network; conversely, a local device may work while its cloud account is unavailable. The comparison narrows the path but does not by itself identify the fault.

Build a short timeline from router events, Home Assistant updates, integration reloads, firmware changes, power interruptions, account changes, and the first failed automation. Correlation is not proof, but a reliable timeline tells you which evidence to inspect and which unrelated changes to leave alone.

Inspect diagnostics without publishing secrets. Useful evidence includes exact timestamps, sanitized error classes, addresses within your private network when appropriate, firmware versions, integration versions, and whether failures are continuous or intermittent. Remove tokens, cookies, serial numbers, email addresses, coordinates, and encryption material.

Change one variable at a time. After each change, repeat the same test and record the result. Simultaneously restarting the router, Home Assistant, bridges, and devices destroys the evidence needed to learn which action mattered and makes recurrence harder to prevent.

Prefer reload over restart when the integration supports it. Prefer reconfigure over delete-and-add when the host or account changed. Prefer a DHCP reservation over hard-coding addresses independently in several places. These choices preserve registry relationships and provide a simpler rollback.

Treat factory reset as recovery, not diagnosis. Before any reset, document pairings, automations, scenes, dashboards, entity IDs, network assignments, encryption keys, and manufacturer-specific recovery requirements. If those cannot be preserved, escalate before resetting.

When service returns, verify both directions: Home Assistant should read fresh state from the device, and a safe command from Home Assistant should be reflected by the device. Also confirm that a physical or vendor-app change is reported back to Home Assistant.

Test the real workflow, not only the device page. Trigger a representative automation in a controlled way, inspect its trace, confirm conditions and targets, and restore the previous state. A device can be healthy while an automation still points to an old entity.

Check recurrence across a normal operating period. Include at least one integration refresh, a DHCP lease check, or the next expected sensor update. For battery equipment, allow for its documented reporting interval instead of assuming silence means failure.

Create a rollback note containing the former value, new value, change time, and verification result. If the change worsens availability or creates duplicate entities, restore the known-good value before trying the next hypothesis.

Escalate with a compact evidence bundle when the problem survives safe local checks: model, firmware, Home Assistant version, integration name, sanitized first error, network topology relevant to the path, steps already attempted, and the smallest reliable reproduction. This gives maintainers actionable information without exposing the household.

Prevent recurrence by documenting address reservations, account ownership, update practices, backup location, integration-specific dependencies, and recovery contacts. Review these notes after router, firmware, or Home Assistant changes rather than waiting for the next outage.

Avoid unsupported certainty. An unavailable state describes a communication result, not necessarily a failed device. Power, privacy controls, address changes, authentication, sleeping behavior, rate limits, firmware, and network policy can create similar symptoms, so evidence must select the branch.

If the problem began immediately after an update, read the official integration documentation and current release notes before downgrading. A migration or renamed entity may be expected. Downgrades can introduce database incompatibility and should never be the first response to a single unavailable entity.

If several unrelated integrations fail together, stop device-specific troubleshooting. Check Home Assistant host health, DNS, time synchronization, network interfaces, Bluetooth or radio adapters, and upstream internet only where the affected integrations require it. Shared failures usually have a shared dependency.

If only one entity fails while sibling entities from the same device remain current, inspect whether it is disabled, unsupported, conditionally exposed, asleep, or dependent on a specific feature. Re-pairing the entire device is disproportionate until those possibilities are excluded.

Verification checklist

Confirm the integration reports loaded, the affected entities have current timestamps, state changes travel in both directions, and the original automation or dashboard works with the expected entity. Repeat the test after a normal reload. Do not declare success from a single momentary update.

Check that no duplicate device or replacement entity appeared. If a new entity ID was created, compare it with automations, scripts, scenes, dashboards, voice-assistant exposure, and history before removing or renaming anything.

Rollback and recovery

If the latest change made the system worse, restore the recorded prior address, option, entity reference, or integration configuration. Reload once and retest. If rollback cannot restore the known-good state, stop making changes, preserve logs, and use the evidence bundle described above.

Safety and privacy warning

Do not disassemble mains-powered SwitchBot products, defeat locks, or repeatedly operate motors against an obstruction. Account synchronization may share device identifiers and encryption material with Home Assistant; protect backups and diagnostic exports accordingly.

Prevention

Keep Home Assistant, the official integration, and device firmware within supported versions, but avoid changing all layers on the same day. Maintain a current backup, reserve stable network addresses where appropriate, label devices by MAC address, and review logs after planned maintenance.

Related Troubliq guides

Start with the Smart-Home Diagnostic Decision Tree, visit the category hub, and compare these related guides: esphome offline still on wifi, matter device unavailable home assistant, homekit device already paired home assistant.

Sources

Primary source: Home Assistant SwitchBot Bluetooth integration documentation. This guide synthesizes the official behavior into a conservative diagnostic order; it does not claim hands-on testing of every model or network.

Frequently asked diagnostic questions

Is a SwitchBot Hub required?

No. Home Assistant’s official SwitchBot Bluetooth documentation explicitly states that a hub is not required. What is required is working Bluetooth coverage from Home Assistant or a suitable proxy.

Why does power cycling sometimes help discovery?

Some devices advertise more actively after a button action or power cycle. This is different from factory reset and can make the device visible without erasing configuration.

What is passive mode?

Passive mode is a Home Assistant Bluetooth adapter setting, not a SwitchBot product type. With the adapter in Passive mode, devices cannot be added through local Bluetooth scanning and must be synchronized through the SwitchBot account while they are within Bluetooth range.

Why would an encryption key be needed?

Some SwitchBot device types encrypt Bluetooth data. Home Assistant needs the correct key ID and encryption key, imported through the supported account route or entered securely.

Can I use Login with Google for synchronization?

The documented integration login flow does not support SSO accounts such as Login with Google. Do not weaken security or share credentials to work around it.

How do I distinguish two identical devices?

Record and compare their Bluetooth MAC addresses, trigger one device at a time, and verify a physical state change. Names and model numbers alone are not sufficient.

Final verification record

Record the date, Home Assistant version, device firmware, integration status, entity IDs checked, commands tested, state-update interval observed, and any network or account change that solved the failure. This record turns today’s repair into a faster and safer response if the symptom returns.

What not to do

Do not respond to an unavailable state by deleting every related device, clearing registries, changing several network rules, or restoring an old backup without first proving the scope. Those actions can create duplicate entities, break historical continuity, invalidate automation targets, and erase the best evidence. Do not follow screenshots from older releases when the current official integration flow differs.

Avoid disabling firewalls, privacy controls, encryption, account protections, or electrical safety features as a test. A safer test is narrow, timed, documented, and reversible. If a proposed action cannot be rolled back or its effect is unclear, collect diagnostics and escalate instead of experimenting on a live household system.

Maintenance check after recovery

One day after recovery, review entity history for another unavailable period, confirm the router or account still shows the expected relationship, and inspect the automation trace from a normal run. Remove temporary diagnostic logging so secrets and storage use do not accumulate, but keep a sanitized summary of the cause and verified fix.

September 20, 2026

Shelly unavailable in Home Assistant: CoIoT, RPC, VLAN, and security diagnostics

Direct answer: When a Shelly device is unavailable in Home Assistant, first confirm that the device still has the expected local IP address and that its own web interface opens from the same network. Then identify the hardware generation. Generation 1 devices depend on CoIoT push traffic, normally sent by unicast to the Home Assistant host on UDP port 5683. Generation 2 and newer devices use RPC and usually require no extra push configuration, although some battery-powered devices may need a correct outbound WebSocket address. Do not factory-reset the device until you have separated an IP or Wi-Fi problem from a CoIoT, WebSocket, VLAN, HTTPS, or authentication problem.

Scope and versions: This guide applies to the official Shelly integration in current Home Assistant releases and to supported Shelly generations. It focuses on local communication between Home Assistant and the device. Shelly BLU devices are a special case: most use the BTHome integration rather than the Shelly integration, while the Shelly BLU TRV is handled differently through a supported gateway. Menu names vary by Shelly generation and firmware, so use the device-generation branch that matches the hardware rather than copying a setting from another model.

Symptoms this guide covers

The Shelly integration shows a device or entities as unavailable.
Switching a relay from Home Assistant fails, but the physical input still works.
The device responds slowly or entity states update only after a delay.
Home Assistant reports that push updates are not reaching it.
A device became unavailable after moving Home Assistant, changing its IP address, adding a VLAN, replacing a router, or enabling Enhanced Security.
A battery-powered Shelly appears only briefly or stopped reporting after a Home Assistant migration.
The Shelly web interface works, but Home Assistant does not receive current state changes.

This guide does not assume that every unavailable state has the same cause. A dead device, unstable Wi-Fi, a changed DHCP lease, blocked local traffic, stale integration configuration, and missing push updates can look similar in the dashboard but require different fixes.

Safety and privacy before troubleshooting

Electrical safety: Many Shelly products are installed behind switches, inside electrical boxes, or near mains voltage. Do not open an enclosure, remove a wall switch, touch terminals, or work on energized wiring to perform network troubleshooting. Use only the device web interface, router, and Home Assistant controls described here. If power cycling requires access to fixed wiring, use the appropriate circuit breaker only if you can identify it safely, or use a qualified electrician.

Before changing configuration, record the device model, generation, firmware version, current IP address, Home Assistant entity IDs, automation references, and any existing CoIoT or WebSocket value. Take screenshots that do not expose passwords, tokens, public IP addresses, precise location data, or wireless credentials. Never post a full Home Assistant diagnostic download publicly without reviewing and redacting it.

Ranked causes

The device is offline or has a different IP address. DHCP changes, weak Wi-Fi, access-point roaming, client isolation, or a router replacement can break the route Home Assistant previously used.
Generation 1 CoIoT push traffic is not reaching Home Assistant. CoIoT may be disabled, the unicast peer may contain an old Home Assistant address, UDP 5683 may be blocked, or the device may not have been restarted after changing the peer.
A VLAN or firewall permits web access but blocks device-to-server traffic. Opening the Shelly page from a laptop proves that one path works; it does not prove that the Shelly can send push traffic to Home Assistant.
A Generation 2+ battery device has a stale outbound WebSocket address. This can occur after moving Home Assistant or changing its internal address.
Enhanced Security or HTTPS configuration changed. On supported Gen2+ firmware, secure local communication can require the expected port and certificate-verification choice.
The integration entry contains stale host information or credentials. This is less common than basic reachability problems and should be addressed after the device and route are verified.
The device is the wrong product type for the Shelly integration. Most Shelly BLU sensors use BTHome, not the Shelly integration.

Step 1: identify the device generation and connection path

Do not begin with a reset. Open the device information in Home Assistant or the local Shelly interface and identify the exact model and generation. The official integration documentation distinguishes four generations and explains that their update paths differ. Generation 1 uses CoIoT. Generation 2 and newer use RPC. That distinction determines which network setting matters.

If the product is a Shelly BLU sensor, check whether it belongs in the BTHome integration. A device appearing in Bluetooth discovery but not in the Shelly integration may be behaving normally. Correct classification prevents unnecessary firmware changes and resets.

Step 2: verify power, IP address, and local reachability

Confirm the device has power using its normal, safe indicator or physical behavior.
Check the router or DHCP server for the device’s current lease.
Compare that address with the host shown in Home Assistant.
From a device on the same trusted LAN, open the Shelly’s local web interface.
Record the firmware version and Wi-Fi signal information if shown.

Interpretation: If the local page does not open and the router has no current lease, troubleshoot power and Wi-Fi before changing Home Assistant. If the router shows a new address and the local page opens there, reserve that address in DHCP and allow Home Assistant to rediscover or reconfigure the device. Do not assign a static address inside the device and a conflicting reservation in the router.

If the device page opens but Home Assistant still reports unavailable, the problem has narrowed to the route between the two endpoints, integration configuration, authentication, or the generation-specific push channel.

Step 3: distinguish complete unavailability from missing push updates

Try one low-risk control from Home Assistant and then change the device through its local web interface or safe physical input. Observe whether Home Assistant eventually catches up.

No control and no state: investigate IP reachability, routing, HTTPS, credentials, and integration host information.
Control works but state updates are delayed or absent: investigate CoIoT on Gen1 or outbound WebSocket behavior on the affected Gen2+ battery devices.
Only one entity is unavailable: review whether the entity is supported, disabled, diagnostic, or dependent on a sensor channel. A whole-device network repair may not be appropriate.
All local devices on one VLAN fail together: suspect routing, firewall, multicast, or client-isolation policy before editing each device.

Step 4: repair Generation 1 CoIoT safely

For a Generation 1 device, open its local interface and verify that CoIoT is enabled. The official Home Assistant Shelly documentation recommends unicast and specifies the Home Assistant server’s local IP address with port 5683 as the CoIoT peer. Use the address Home Assistant actually has on the local network, not its public domain, a Cloudflare address, or a remote-access URL.

Record the existing CoIoT peer.
Confirm Home Assistant’s stable internal IP address.
Set the peer to HOME_ASSISTANT_IP:5683.
Save the setting.
Restart the Shelly device as instructed by the official documentation.
Wait for it to reconnect before testing state changes.

Battery-operated Generation 1 devices require this unicast configuration even when connected by USB. If the Shelly and Home Assistant are on different subnets, allow the necessary UDP 5683 traffic from the device network to the Home Assistant host. Create the narrowest rule that fits the path; do not expose UDP 5683 to the internet and do not disable an entire firewall as a test.

If the CoIoT setting is missing, check whether the device firmware is extremely old. Review the manufacturer’s release information and update through the official device interface only after preserving settings and confirming stable power. Do not interrupt a firmware update.

Step 5: check Generation 2+ RPC and outbound WebSocket

Generation 2 and newer devices use RPC and normally need no additional configuration. Therefore, do not add a WebSocket merely because a mains-powered Gen2 device is unavailable. Start with IP reachability, routing, authentication, and security settings.

The documented exception is certain battery-operated devices, including devices temporarily connected by USB, when Home Assistant cannot determine the correct internal URL or when the device still points to a different Home Assistant instance. In that case, check Settings → Connectivity → Outbound WebSocket in the device interface. The documented path uses:

ws://HOME_ASSISTANT_LOCAL_IP:8123/api/shelly/ws

If the local Home Assistant endpoint itself uses HTTPS with a suitable certificate, use the corresponding wss:// form. Do not use wss:// simply because the public website or remote-access domain uses HTTPS; the device must be able to validate and reach the exact local endpoint configured.

After correcting a stale address, save the change and let the device reconnect. Avoid running two active Home Assistant instances that both try to control the same device during a migration.

Step 6: test VLAN, firewall, and Wi-Fi behavior

A useful diagnostic is to draw the actual path: Shelly IP, wireless access point, IoT VLAN, router or firewall, and Home Assistant IP. Test each boundary. Common policy mistakes include wireless client isolation, a rule that permits established connections in only one direction, a guest network that blocks local destinations, and a firewall that allows TCP web access but not the UDP traffic needed by Gen1 CoIoT.

Do not permanently move every device to the main LAN as a shortcut. If a temporary same-network test makes the problem disappear, that result identifies a routing or policy issue. Recreate the required narrow local flow, then return the device to the intended network.

For unstable Wi-Fi, compare behavior close to the access point and review signal strength. The official documentation notes that access-point roaming can help on networks with several access points. Avoid changing channel width, roaming, band steering, multicast, and firewall rules simultaneously; one change at a time preserves the ability to identify the cause.

Step 7: review Enhanced Security and HTTPS

Supported Gen2+ devices can use Enhanced Security. The Home Assistant integration detects this and communicates over HTTPS on port 443. Devices shipped with supported newer firmware may have factory-provisioned certificates, while devices upgraded later may require a separately installed certificate before Enhanced Security can be used as intended.

If Enhanced Security was enabled immediately before the failure, confirm that Home Assistant can reach port 443 on the device and review the integration’s certificate-verification setting. Enable certificate verification only when the presented certificate chains to a certificate authority trusted by Home Assistant. Leaving verification disabled for a self-signed or internally provisioned device certificate is different from turning off encryption entirely. Do not upload unknown certificates or bypass warnings on a public interface.

Step 8: reload only after the network path is correct

Once reachability and the generation-specific channel are correct, reload the Shelly integration entry. If the device has a new IP address, allow discovery or use the supported reconfiguration flow. Avoid deleting the integration first: deletion can disrupt entity IDs, device associations, dashboards, histories, and automations without fixing the network cause.

If reauthentication is requested, use the device’s current local credentials. Do not paste passwords into logs or community posts. If a credential change is necessary, record which automations or external systems also rely on that account.

Verification checklist

The device’s local page opens at the expected reserved IP address.
Home Assistant shows the device and main entities as available.
A safe command from Home Assistant reaches the device.
A physical or local-interface change appears promptly in Home Assistant.
No new Shelly repair issue appears after a restart.
The device remains available after restarting Home Assistant.
The device remains available after restarting the router or access point.
Automations referencing the established entity IDs still run.

Verification after both endpoint and network restarts matters. A fix that works only until the next DHCP renewal or reboot is not complete.

Rollback and recovery

If a configuration change makes the device less reachable, restore the recorded CoIoT peer, WebSocket URL, security option, or DHCP reservation one change at a time. Keep Home Assistant’s integration entry intact while rolling back. If a firmware update introduced the behavior, do not install unofficial firmware or attempt an unsupported downgrade; consult the manufacturer’s documented recovery path.

A factory reset is the last resort. Before resetting, export or record device schedules, calibration, input mode, power-on behavior, Wi-Fi configuration, authentication, and automation references. For a mains-wired relay, follow the model’s official manual and use a qualified electrician when physical access is required.

When to escalate

Escalate when the device repeatedly reboots, disappears from DHCP despite good power and Wi-Fi, rejects its own local interface, shows certificate errors you cannot explain, or remains unavailable after the documented local path is verified. Provide the exact model, generation, firmware, Home Assistant version, installation type, network topology, redacted error text, and whether local control works. State whether the failure affects command traffic, push updates, or both.

Do not publish device credentials, backup archives, serial numbers that function as secrets, precise public addressing, or unredacted diagnostics. Community reports can help identify patterns, but the official integration and manufacturer documentation should control safety-sensitive changes.

Prevention

Reserve stable DHCP addresses for Home Assistant and fixed smart-home infrastructure.
Document Gen1 CoIoT peers and Gen2+ WebSocket settings before migrations.
Use narrow, documented firewall rules between IoT networks and Home Assistant.
Change one network or security setting at a time and verify afterward.
Maintain a current Home Assistant backup before integration or network migrations.
Review repair notifications instead of disabling them without understanding the tradeoff.
Keep firmware current through official channels, with stable power during updates.
Preserve entity IDs when reconfiguring to avoid breaking automations.

Diagnostic matrix

Observed result	Most likely layer	Next safe check
No DHCP lease or local page	Power or Wi-Fi	Confirm safe power state, access point association, and signal
Local page works; no Home Assistant control	Routing, host, HTTPS, or credentials	Compare IP, ports, VLAN route, and integration entry
Control works; state is stale on Gen1	CoIoT push path	Enable CoIoT, verify unicast peer and UDP 5683
Battery Gen2+ stopped after migration	Outbound WebSocket	Remove the old Home Assistant address and set the current local endpoint
Failure began after Enhanced Security	HTTPS or certificate handling	Verify port 443, certificate source, and Verify SSL choice
Every device on one IoT VLAN fails	Network policy	Inspect routing, isolation, and narrowly scoped firewall rules

Sources and testing disclosure

Testing disclosure: This guide is based on current official documentation and protocol-specific diagnostic reasoning. Troubliq did not claim hands-on testing with every Shelly generation, firmware revision, network topology, or security configuration.

Last reviewed: September 18, 2026.

Continue troubleshooting

September 20, 2026

Home Assistant automation stopped triggering: step-by-step diagnosis
Short answer: Open the automation trace and confirm whether the trigger fired. If no trace exists, inspect the trigger and source entity. If a trace exists, follow it through conditions and actions instead of editing several steps at once.

Preserve the failure

Record when the automation last worked, the expected trigger time, the relevant entity states, and recent changes to Home Assistant, integrations, devices, helpers, or YAML. Do not delete and recreate the automation yet.

1. Confirm it is enabled

Check that the automation is enabled and that its mode is appropriate. Review the logbook for an unexpected disable event, reload, restart, or conflicting automation.

2. Look for a trace

A trace shows whether the trigger fired and where execution stopped. No trace usually points toward the trigger, source entity, or scheduling context. A trace ending at a condition means the automation worked as written but the condition evaluated false.

3. Inspect the trigger

Check entity IDs after device replacement or integration migration. For state triggers, distinguish a true state change from an attribute update. For numeric triggers, remember that crossing a threshold is different from already being beyond it. For time triggers, check the system timezone and helper value.

4. Test conditions with real states

Use the trace values from the failed run. Templates may receive unavailable, unknown, text, or null values. Confirm units and data types rather than assuming the displayed dashboard value is the raw state.

5. Test actions safely

Run only actions that are safe to test. Avoid unlocking doors, disabling alarms, opening valves, changing HVAC safety settings, or operating equipment without supervision. Verify target entities, service names, permissions, and integration availability.

6. Check concurrency

Single, restart, queued, and parallel modes behave differently when triggers overlap. A long delay or wait can make a single-mode automation appear unresponsive. The trace and system log should show dropped or cancelled runs.

Make one change

Duplicate or export the automation before a structural edit. Change one confirmed cause, reload if required, reproduce the trigger, and compare the new trace. If the failure began after an update, consult current release notes and official documentation before applying a workaround.

Video walkthrough: trace an automation failure

Michael Leen demonstrates how to follow Home Assistant automation traces and isolate the exact trigger, condition, or action that stopped a run. Use the video as a visual companion to the checks above; keep the written steps open so you can record each result and change only one variable at a time.

Video: “Home Assistant Automation Not Working? Do THIS First!” by Michael Leen. Embedded from the creator’s original YouTube upload.

Official sources
- Home Assistant automation testing and troubleshooting
- Home Assistant automation modes
Last reviewed: September 4, 2026.

Find your next troubleshooting path
Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

Detailed evidence checklist for Home Assistant automation stopped triggering

Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

Network tests that prove the failing layer

Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

Configuration comparison procedure

Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

Power, radio, and timing checks

Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

Log-reading workflow

Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

Safe change order
1. Correct time, power, cabling, or an obviously stale address.
2. Reload only the affected integration when documentation supports it.
3. Use Reconfigure or Reauthenticate without deleting the entry.
4. Restart only the affected device or add-on during a safe window.
5. Restart Home Assistant when several components share the symptom or a change requires it.
6. Update software after reading release notes and preserving rollback.
7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.
Post-repair validation

Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

When to stop and escalate

Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.

Verification checkpoint 1 focuses on trigger observation. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 1: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

For checkpoint 2, inspect trace creation rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 2: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Checkpoint 3 — condition result: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 3: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Verification checkpoint 4 focuses on choose branch. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 4: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

For checkpoint 5, inspect target entity rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 5: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Checkpoint 6 — automation mode: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 6: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Verification checkpoint 7 focuses on delay or wait. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 7: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

For checkpoint 8, inspect template variables rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 8: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Checkpoint 9 — YAML reload: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 9: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Verification checkpoint 10 focuses on service response. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 10: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

For checkpoint 11, inspect restart behavior rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 11: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Separate trigger failure from condition or action failure

Open the automation trace before editing YAML. If no trace exists for the expected event, the trigger did not fire. If a trace exists and stops at a condition, the trigger worked and the condition evaluated false. If the trace reaches the action sequence, inspect the exact action result, target and service response. This distinction prevents rewriting a correct trigger when the real problem is downstream.

In Developer Tools, observe the entity state or event that should start the automation. State triggers compare exact state strings and do not behave like numeric comparisons. Numeric-state triggers fire when a value crosses a threshold, not continuously while it remains beyond that threshold. Time, sun, template and event triggers each have their own restart and availability behavior.

Check modes, waits and overlapping runs

Review the automation mode. In single mode, a long delay or wait can block a new run. Restart mode cancels the previous run, queued mode preserves order, and parallel mode permits overlap. Choose the mode based on the device and intended behavior; changing it without understanding concurrency can create duplicate commands.

Inspect wait templates, choose branches and templated targets using real trace variables. Confirm entity IDs still exist after device replacement or integration reload. A dashboard label may look unchanged while the underlying entity ID has changed. Reload automations after YAML edits and check the configuration before restarting Home Assistant.

Verify the automation deterministically
- Reproduce the actual trigger instead of pressing “Run actions” only.
- Confirm the trace shows the expected trigger data.
- Check every condition result and selected choose branch.
- Verify the target entity receives the service call.
- Repeat after a normal reload or restart.
Running actions manually bypasses triggers and may bypass trigger-dependent variables, so it cannot prove the complete automation works. Use a safe test value or event, capture one trace and restore the original state afterward. If the automation fails only after restart, examine unavailable startup entities, template initialization and required delays rather than adding arbitrary repeated actions.
September 5, 2026

Category: Hubs & Automations

UniFi Protect unavailable in Home Assistant: authentication, API mode, streams, and NvrError fixes

Symptoms and exact scope

Before changing anything

UniFi Protect failure matrix

1. Confirm supported hardware and software

2. Test the console locally

3. Understand full access versus API-key-only mode

4. Verify the local user correctly

5. Validate the API key without exposing it

6. Diagnose missing or delayed camera streams

7. Interpret NvrError 404 and 502 safely

8. Explain entities that disappear by design

9. Verify recovery

Rollback and recovery

Prevention

Related Troubliq guides

Sources and review record

Samsung TV not authorized in Home Assistant: permissions, token, network, and Wake-on-LAN fixes

Symptoms and scope

Before making changes

Fast diagnostic matrix

1. Confirm the television itself is online

2. Check model and protocol compatibility

3. Repair an incorrect IP address safely

4. Fix repeated Samsung permission prompts

5. Diagnose VLAN and subnet failures

6. Fix “turn off works, turn on does not”

7. Interpret Wake on LAN results

8. Test remote commands and sources logically

9. Capture useful diagnostics

Verification checklist

Rollback and recovery

Prevention

Related Troubliq guides

Evidence, applicability, and safe verification

Sources and review record

SwitchBot device not discovered in Home Assistant: Bluetooth and passive-mode diagnosis

Symptoms and scope

Prerequisites and evidence to preserve

Likely causes

Least-destructive diagnostic sequence

Diagnostic asset: choose the next branch

Deeper checks when the first sequence does not solve it

Verification checklist

Rollback and recovery

Safety and privacy warning

Prevention

Related Troubliq guides

Sources

Frequently asked diagnostic questions

Is a SwitchBot Hub required?

Why does power cycling sometimes help discovery?

What is passive mode?

Why would an encryption key be needed?

Can I use Login with Google for synchronization?

How do I distinguish two identical devices?

Final verification record

What not to do

Maintenance check after recovery

Shelly unavailable in Home Assistant: CoIoT, RPC, VLAN, and security diagnostics

Symptoms this guide covers

Safety and privacy before troubleshooting

Ranked causes

Step 1: identify the device generation and connection path

Step 2: verify power, IP address, and local reachability

Step 3: distinguish complete unavailability from missing push updates

Step 4: repair Generation 1 CoIoT safely

Step 5: check Generation 2+ RPC and outbound WebSocket

Step 6: test VLAN, firewall, and Wi-Fi behavior

Step 7: review Enhanced Security and HTTPS

Step 8: reload only after the network path is correct

Verification checklist

Rollback and recovery

When to escalate

Prevention

Diagnostic matrix

Sources and testing disclosure

Continue troubleshooting

Home Assistant automation stopped triggering: step-by-step diagnosis