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
- Home Assistant UniFi Protect integration documentation
- Home Assistant UniFi Network integration documentation
- UniFi Protect developer documentation
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.