This guide helps troubleshoot and resolve adoption issues on the UniFi Network Controller.
NOTES & REQUIREMENTS: Please make sure to have read and followed the instructions on the UniFi - Device Adoption article before proceeding.
Table of Contents
- Potential Adoption Failure Causes and How to Solve
- Unable to Discover Device
- USG Specific Adoption Issues
- Related Articles
Potential Adoption Failure Causes and How to Solve
Single Device is Presenting Adoption Issues
A valuable point of consideration when troubleshooting adoption issues is determining the scale of the issue. Knowing whether you are unable to adopt only one device or all devices will help you identify where the issue lies.
When a single device cannot be adopted, this suggests a device-specific issue for example:
- LED OFF: Indicates device is not powering successfully or device is online and is managed by a Controller that has disabled LED status.
Solid White LED: Indicates device is ready and waiting for adoption. If you are unable to discover it from the controller this suggests that necessary connectivity between device and controller is not present, for example, if they're not on the same network. This article might help: UniFi - Device Adoption Methods for Remote UniFi Controllers.
Solid Blue LED: This indicates the device is already adopted by a controller. Either the device was adopted successfully and now cannot connect to the controller, or the device is being managed by another controller which could prevent discovery. This sometimes happens when trying to adopt a device previously managed by another controller, even after reset. Disconnecting the host of the other Controller (for example the Cloud Key that was previously hosting that controller) to make sure it is out of reach is helpful. Another good practice is "Forgetting" the device from the previous controller to avoid its re-adoption to that old Controller.
The device might be in a faulty state that will be resolved with a factory reset. If after performing a hard reset via the reset button and "forgetting" the device from the UniFi Controller (if possible), you still cannot adopt the device, try the following:
1. Establish SSH connection with the device. See this article for guidance: Intro to Networking - How to Establish a Connection Using SSH
2. Type the following command followed by enter:
sudo syswrapper.sh restore-default
3. Once device reboots, SSH into the device again and type the following command, substituting the "ip-of-controller" with the IP address of the host of the UniFi Network Controller:
4. After the set-inform command executes, the UniFi device will show up in the Devices section of the Controller. Wait until it does, and click Adopt to begin the adoption process.
Update Device Firmware
It might be that the device needs a firmware upgrade to allow adoption to the current Controller version. Find the most recent stable firmware on the Downloads page and follow the SSH instructions to upgrade your device from this article: UniFi - Changing the Firmware of a UniFi Device.
Subnet, Network Location, or Uplink
If all devices connected to a certain switch are unable to be adopted, check to make sure that VLAN configuration on the switch isn’t preventing devices from connecting to the UniFi Network Controller.
Watch the Controller Logs when attempting to adopt a device. Take note if the output is a message of a successful adoption, or the error message associated with a failure. Also see Device Logs by connecting via SSH to the devices you are struggling to adopt and running
var/log/messages for indication of why adoption failed and compare to working devices. See this article for further information on how to view log files.
All Devices are Presenting Adoption Issues
If all devices are un-adoptable this suggests an issue more on the Controller side or network-wide.
Ports Blocked by Firewall
- Can discover devices, have no difficulties being able to initiate device adoption through the controller.
- Can ping and SSH into devices.
- The device stays in "Adopting" status until eventually device changes to "Adoption Failed" status.
- The device never goes to a Provisioning status, which is the status returned that indicates that the AP could connect to the controller to pull down its initial configuration
- This all indicates that traffic can go out to the AP from the controller, but not inbound from the controller. Since firewall policies typically only restrict inbound traffic this is consistent with firewall issues.
To resolve, make sure that port 8080 is open inbound on the machine hosting the UniFi Controller. Additionally, make sure that any firewall device in between the controller and the device is configured to permit traffic from the necessary ports. See this article for a list of all ports needed to ensure proper function of UniFi: UniFi - Ports Used.
DHCP Server Issue
This issue arises when the UniFi Access Point (UAP) continues with the default IP of 192.168.1.20, indicating an issue with the DHCP server.
- Make sure that the DHCP server is active (the router in the network may be performing this function).
- If the router is leasing DHCP address to the UAP, try to ping or make an SSH connection to the UAP.
- From the Controller, make sure the AP does obtain the IP from DHCP, take note of the IP from the Controller, SSH into the AP (using the IP, the device authentication username and password) and obtain the logs by issuing the command:
tail -f /var/log/messages.
The logs may be helpful if none of the solutions in this article help and you need to ask about it in the Community. Be sure to copy and paste them in a saved file for later use.
Network Topology Issues
- In some cases, unable to discover devices.
- May be able to discover devices, but attempting to adopt a device returns "Adoption Failed".
- You may be able to ping devices, have verified local firewall is open over necessary ports, but still get adoption failures.
- Often occurs when the controller is being accessed over wireless, or when the machine you are connecting to the controller with has both wireless and wired NICs.
Example of Potentially Problematic Network Topology:
In cases where you have two NAT devices like a modem/router combo and a USG, there is the possibility of network overlap between the USG and modem-router combo. This can result in no internet connectivity for the devices that are behind the USG. To fix this issue the modem/router should be put into bridge mode. If you do not have management access to this modem/router, contact your ISP provider to make this configuration change.
Unable to Discover Device
If a UniFi device shows the LED pattern for "ready and waiting adoption", but is not discoverable to adopt, and does not appear in the UniFi Network Controller's Devices section as "pending adoption" please follow these steps.
1. Begin by making sure that the Controller (its host) is connected to the same network as the device that you are attempting to discover.
2. Verify that all ethernet cables are connected firmly to the corresponding network device (switch or router, depending on the deployment). It's a good idea to switch ethernet cables to confirm it's not a faulty cable problem.
3. Verify that the firewall and any antivirus software is temporarily disabled, to make sure they are not blocking any ports that need to be open.
4. After firewall and antivirus software is disabled restart the UniFi Network Controller in order for the software to see those changes.
5. Upgrade the UniFi Network Controller software and the device's firmware. The discrepancy between the device firmware and the controller software can cause devices to not be discovered. Here are some articles explaining how to perform these upgrades:
- UniFi Network Controller software: hosted on macOS, Windows and Windows Server and Debian-based Linux (Ubuntu, Mint, and others).
- UniFi Network Controller software: hosted on a Cloud Key (similar process for UniFi Dream Machine models).
- Device firmware: This article provides instructions on upgrading via the controller, and alternatively how to perform an upgrade via SSH, if there is no access at all via the controller.
- Cloud Key firmware: Remember that if the controller is hosted on a Cloud Key (or UniFi Dream Machine), its firmware must also be updated.
6. If after updating the device and controller (and refreshing the controller), the device is still undiscoverable please proceed to try the manual adoption process described in this article using the steps for SSH.
USG Specific Adoption Issues
NOTE: Settings that are applied in CLI or webUI on the USG do not survive through controller provisioning.
When also troubleshooting adoption issues, if the device in question is a USG these scenarios can cause issues:
- When adopting the USG into an already existing network: If the USG WAN interface subnet overlaps the same subnet on the LAN interface (default 192.168.1.0/24) routing to the proper interface will not happen as expected. Either replace the upstream device with the USG or change the LAN subnet on the USG local UI. Take a look at this article: UniFi - USG: How to Adopt a USG into an Existing Network.
- When adopting the USG to a Controller that is reachable over the internet: The USG will need an "inform address" to phone home to. See this article for more information about how to accomplish setting an inform address.
- Setting a non-default management network subnet: The default LAN interface subnet is 192.168.1.0/24. If it is desired to change this subnet, the recommended process would be to set the new subnet in the local UI of the USG before attaching a LAN where the controller host will be located. This will ensure that the controller is on the desired subnet before trying to adopt devices.
ATTENTION: After setting up the controller, but before adopting the USG verify that the LAN network in the controller settings has been changed to the new subnet. If this setting is not changed the default 192.168.1.0/24 will be provisioned over the settings that were changed on the USG UI.