UniFi Device Adoption Troubleshooting That Works

Adoption is where new UniFi users lose the most time. A device shows up, you click Adopt, and it sits on “Adopting…” forever, flips to “Disconnected,” or never appears at all. Almost every case is one of a small number of causes. This guide is the model of how adoption works plus an ordered recovery method, so you stop guessing.

What adoption actually is

Adoption is the handshake where a UniFi device and your controller establish a managed, authenticated relationship. After adoption, provisioning is the controller pushing configuration down. Both can fail, and the status text tells you which stage you’re stuck in:

• Pending Adoption / Adopting: the device and controller can see each other but haven’t completed (or are failing) the handshake.
• Provisioning (stuck): adopted, but configuration push isn’t completing.
• Disconnected: the controller has lost contact with a device it believes it manages.
• Managed by Other / Adoption Failed: the device already holds credentials for a different controller (or a stale set), so a new controller can’t take it cleanly.

Reading the status before acting saves you from applying the wrong fix.

The core concept: the device must find the controller

A UniFi device needs to know where the controller is. There are two ways that happens:

• Layer 2 adoption: device and controller are on the same subnet/VLAN. The device discovers the controller via broadcast. This is the simple, default path and the one to use whenever possible.
• Layer 3 adoption: device and controller are on different subnets (different VLAN, different site, controller in the cloud). Broadcast discovery doesn’t cross subnets, so the device must be told the controller address — via DHCP option, DNS, or setting it on the device directly.

A huge fraction of “adoption won’t work” is actually “I put the device on a different VLAN than the controller and expected Layer 2 discovery to still work.” It won’t — that’s Layer 3 and needs an explicit pointer.

The single most common cause: VLAN mismatch

If you’ve started segmenting your network (see our VLAN guide) and adoption broke right after, this is almost certainly it. The new device booted onto a VLAN where it cannot reach the controller, or where broadcast discovery doesn’t reach it.

Fixes, in order of preference:

1. Adopt on the controller’s VLAN first, then move it. Plug the device into a port on the same network as the controller, let it adopt and provision cleanly, then reassign it to its intended VLAN. Easiest and most reliable.
2. Provide a Layer 3 pointer if devices must come up on another subnet: a DHCP option or DNS record that resolves the controller’s address for that subnet, so devices there can find it without broadcast.

If a device adopts fine on the management VLAN but not on its target VLAN, the problem is discovery/routing on that VLAN, not the device.

The “Managed by Other” / stale-credentials case

If a device was previously adopted (by an old controller, a previous owner, or an earlier install you tore down), it still holds those credentials and will refuse a clean adopt elsewhere. The cure is to clear the device’s state so it forgets its old controller, then adopt fresh. Conceptually you are returning the device to a default, unmanaged state and re-introducing it. After that, treat it as a brand-new device on the correct VLAN.

This is why second-hand UniFi gear so often “won’t adopt”: it’s not broken, it’s still loyal to a controller it can’t reach.

Provisioning that never finishes

Adopted but stuck provisioning usually means the device got the adoption handshake but can’t complete the configuration exchange:

• Intermittent connectivity between device and controller (flaky uplink, marginal PoE, a switch port renegotiating). A device power-cycling mid-provision will loop.
• Firmware gap. A device on very old firmware adopting to a much newer controller can struggle; letting it update (or updating it out-of-band) often clears it.
• The device is also being fought over by another controller instance on the network (e.g., a leftover controller VM you forgot is running). Two controllers both trying to manage one device produces flapping. Make sure exactly one controller is active.

Power and link: the boring causes that look like software

Before deep controller debugging, rule out the physical layer, because these masquerade as adoption bugs:

• PoE budget / insufficient power. An access point that boots, partially comes up, then resets mid-adoption is a classic underpowered-PoE symptom. Confirm the switch port can actually deliver the power class the device needs and the device is on an appropriate PoE port.
• Bad cable / marginal link. A link that negotiates but drops under load will cause a device to disconnect right as provisioning pushes data. Reseat or replace the cable; check the port’s error counters.
• Device not actually finished booting. Some devices take a few minutes on first boot and after firmware changes. “Stuck” for 30 seconds is not stuck.

An ordered recovery method

Work top to bottom; stop when it’s fixed:

1. Read the status. Adopting vs Provisioning vs Disconnected vs Managed-by-Other — each points at a different cause above.
2. Confirm one controller. Make sure no second/old controller is also live on the network.
3. Check power and link. Adequate PoE, good cable, device fully booted. Resolve these before anything else.
4. Same VLAN as controller? If not, either adopt on the controller’s VLAN then move it, or provide a Layer 3 pointer for that subnet.
5. Stale credentials? If it claims it’s managed elsewhere or repeatedly fails, return the device to default/unmanaged state and adopt fresh.
6. Firmware gap? Let it (or force it to) update, then re-provision.
7. Then, and only then, consider controller restore or deeper logs — most cases never get here.

The reason adoption feels mysterious is that one symptom (“won’t adopt”) has several unrelated causes. Identify the stage from the status, eliminate power and Layer 2/Layer 3 reachability first, and the rest is straightforward. For the groundwork this assumes and the cases it connects to, see controller hosting options, the firmware and update strategy behind version-mismatch stalls, multi-site remote adoption, and the rest of our UniFi guides.