Unifi Home Assistant Problems? A Complete Fix Guide

Solving Unifi Home Assistant Integration Problems

Integrating your Unifi Network or Unifi Protect system with Home Assistant unlocks powerful automation possibilities, from presence detection based on Wi-Fi connections to triggering alerts from security cameras. However, when the connection between these two powerful systems breaks, it can be tricky to diagnose.

This guide provides a clear, step-by-step approach to troubleshooting and fixing the most common problems encountered with the Unifi Home Assistant integration.

Understanding the Core of the Connection

The Home Assistant integration communicates directly with your Unifi Network Application (the controller), not with the devices themselves. This means that for the integration to work, Home Assistant must be able to establish a stable network connection to your controller's IP address and authenticate successfully. Most problems originate from a failure in one of these two areas.

Troubleshooting Your Unifi Integration: A Checklist

Follow these steps methodically to identify and resolve the issue.

1. Verify Unifi Controller Accessibility

Before anything else, confirm that Home Assistant can actually 'see' your Unifi controller on the network.

• Check the IP Address: Ensure the IP address of your Unifi Controller (e.g., Cloud Key, UDM, self-hosted server) is correct in the Home Assistant integration settings. If your controller has a dynamic IP, it's best to assign it a static IP address or a DHCP reservation in your router.
• Firewall Rules: This is a very common issue. If Home Assistant and your Unifi controller are on different VLANs (or subnets), you must have firewall rules that allow traffic to flow between them. Home Assistant needs to be able to make outbound connections to the Unifi controller's IP on its specific port (typically 443 or 8443 for HTTPS).

2. Use the Correct User Credentials

You should not use your main Ubiquiti cloud account (email and password) for the integration. You must create and use a local administrator account.

• Create a Local Admin Account:
  1. Log in to your Unifi Network Application.
  2. Go to Settings → Admins.
  3. Create a new admin user.
  4. Set the role to 'Administrator' (or 'Read Only' if you only need presence detection).
  5. Crucially, ensure the account type is set to 'Local Admin', not 'Cloud Access'.
• Update Credentials in Home Assistant: Go to your Home Assistant Settings → Devices & Services, find the Unifi integration, and re-configure it using the username and password for the new local admin account you just created.

3. Select the Correct Unifi 'Site'

If you manage multiple locations or have separated devices into different 'sites' within the Unifi controller, the integration might be looking in the wrong place.

• Check Site Configuration: In Home Assistant, go to the Unifi integration's configuration options. You should see a field for 'Site'. Make sure the site name selected here exactly matches the site name in your Unifi controller where the devices you want to control are located. The default is usually 'Default'.

4. Review Home Assistant Logs

The logs are your best friend for diagnosing complex issues.

• Find the Logs: In Home Assistant, go to Settings → System → Logs.
• Look for Errors: Scan the logs for any entries containing the word unifi. Error messages like Authentication failed point directly to a credential problem, while Connection refused or Timeout strongly suggest a network or firewall issue.

By systematically working through these four key areas—accessibility, credentials, site selection, and logs—you can solve nearly all Unifi integration problems and restore the powerful connection to your smart home.