The UniFi device adoption process is necessary to manage and configure devices in the UniFi Network Controller. This guide helps troubleshoot and resolve adoption issues.
NOTES & REQUIREMENTS: Please make sure to have read and followed the instructions on the UniFi - Device Adoption article before proceeding.
Table of Contents
- Narrowing Down Potential Causes
- Most Common Causes of Adoption Failures
- USG Specific Adoption Issues
- Related Articles
Before troubleshooting an adoption issue, it is important to first check to ensure all the following requirements are met:
- All necessary ports need to be open on the controller and on the local network. Reference this article to verify that the required ports are open.
- The UniFi Controller and UniFi device must be able to communicate with each other over the network.
- The UniFi device must not be managed by another UniFi Controller or needs to be reset to a factory default state. See Related Articles for help on these topics.
- If the device has been reset and is being readopted to a new controller, make sure the previous controller is no longer accessible to the device to ensure it is not re-adopted automatically. For example, if previous controller was hosted in a UniFi Cloud Key that is still connected to the network, disconnect that Cloud Key to make sure it is truly out of reach.
Once these requirements are confirmed to be in place, test the adoption again. If the device is not adopted, proceed with troubleshooting the issue.
Narrowing Down Potential Causes
When troubleshooting adoption issues there are a number of potential causes and issues that could be at play. It is very important to narrow issues down as much as possible to a smaller number of potential causes; this will avoid expending unnecessary time and effort. Here are some ways to do that:
One or Many Devices?
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 singled device cannot be adopted, this suggests a device-specific issue for example:
- Bad ethernet cable preventing the UAP from powering up.
- The UAP may be in a faulty state and needs to be factory reset.
- Device firmware needs to be updated.
What’s different about these devices?
When one or multiple devices can be adopted while others cannot, it’s important to figure out everything that’s different about them. For instance:
- Device Model: If only one particular AP model is having issues, that could potenitally indicate that a firmware update is needed for thas device. Reference this article for more information on how to upgrade firmware on a device that is not adopted.
- Subnet, Network Location, Uplink, etc.: All devices connected to a certain switch are unable to be adopted, check to make sure that VLAN config on a switch isn’t preventing devices from connecting to the UniFi Controller.
- Check Logs: 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 checking `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.
When all devices are un-adoptable this suggests an issue more on the Controller side or network-wide, for example:
- Network connectivity issues.
- Ports being blocked by a firewall.
- The Controller needs to be updated to the current stable version. See here for current versions of the UniFi Controller.
Checking the Device's LED Status
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 in default state/should be able to be discovered and adopted. If you are unable to discover it from the controller this suggests that necessary connectivity between device is not present, or if you’re managing the device from a remote site that you need to follow instructions here: UniFi - Device Adoption Methods for Remote UniFi Controllers
Solid Blue LED
This indicates the device is already adopted/configured 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.
For more information about device LED patterns, reference this article: UniFi - LED Color Patterns for UniFi Devices
Most Common Causes of Adoption Failures
Ports Blocked by Firewall
The most common cause for adoption failures is lack of required port connectivity over TCP Port 8080 from the device to the controller. This is most often a result of a firewall blocking traffic either inbound on the controller machine’s firewall policy or by a firewall device.
- 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 default username/password) and obtain the logs by issuing: tail -f /var/log/messages.
The logs may be helpful for a support case or post on the Community. Be sure to copy and paste them in a saved file for later use.
Network Topology Issues
Network topology can disrupt/prevent the adoption of UniFi devices if not set up properly. Your network topology may be preventing you from discovering devices, cause adoption failed error, etc. If you have verified that the firewall is open as it should be, you may be dealing with an issue with how you’ve connected the devices/controller to each other.
- 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.
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.
- 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.