Skip to main content
A node that does not answer is usually reachable by a route you have not tried, not broken. Work through reaching it before you reach for a card reader. For symptom-by-symptom diagnosis by product, start at Troubleshooting by area.

Reaching a node that stopped answering

Try the name the agent advertises

The agent publishes an mDNS service (_ados._tcp, port 8080) and the resolvable name is the box’s system hostname, the one you set at install time:
The installer prints this URL on its completion summary. It is the address to keep, because unlike an IP address it survives the box getting a different lease.
.local resolution is not guaranteed. It has been observed failing on a box that was otherwise healthy and answering on its address. mDNS depends on the responder running on the node, on your own machine resolving mDNS at all, and on the network passing multicast. A name that does not resolve is not evidence of a dead node.Equally, a recorded IP address goes stale when the lease changes. Neither route is reliable on its own, which is why the agent advertises several and why you should try more than one before concluding anything.

Try the other routes

The agent advertises every way it can be reached, in priority order: the mDNS name, then per-interface LAN addresses, then the hotspot, then USB, then a cloud tunnel if one is configured. Any of them that is up will work. Both the access point and the USB gadget subnets are treated as operator routes by the agent even when it is unpaired, so they stay usable on a box you cannot otherwise reach. If you do not know the address, scan the network for the hostname rather than guessing at old addresses.

Check it from the box itself

If you can get a shell on it:
Then read the journal, which is the log of record:
The Black Box store is off by default (logging.store.enabled: false). Unless you enabled it, ados logs query and ados logs tail have nothing to return; use journalctl -u <unit>. Where the store is on, it survives reboots and holds telemetry and hardware history alongside the log lines. See Black Box.
Check whether services are up:
The units each profile runs are listed on Systemd services.

Three symptoms to triage first

The node will not boot

A node that gets no further than a blank screen or a boot loop is not reachable over the network, so the checks above do not apply. Work in this order.
  1. Power first. An under-powered supply, or an adapter drawing more than the rail can carry, presents as a board that boots partway and restarts. Once the node is reachable again, ados diag storage reports the board’s own undervoltage and thermal-throttle flags, which is worth checking on any node that has been rebooting on its own.
  2. Read the card on another machine. A full filesystem and a corrupted root are both visible from a card reader, and both look identical from the outside.
  3. Reflash. If the card is intact and the box still will not come up, this is the supported recovery. See Reflash and reinstall.
A node that reboots repeatedly, rather than failing to start once, is worth investigating before reflashing. Reflashing clears the evidence, and a cause that is still present will reappear. If the box is reachable at all between reboots, collect a support bundle first.
Check the link and the pairing as two separate questions, because they fail separately and the answers point in different directions.
Read the link state rather than the packet counters alone. rf_unverified is the one to know: this end is transmitting and nothing has confirmed receiving it. A transmitter with no listener looks identical to a healthy transmitter when you only look at the transmit side, so this state is reported as unverified instead of connected.
A well-formed radio key is not a working radio key. If one end has been reflashed or re-imaged, the other end may still hold a key for a peer that no longer exists. It will transmit into nothing while every local check passes, because the key file itself is valid.If ados diag link shows this end transmitting with nothing decoding, and both ends claim to be paired, re-pair them rather than continuing to diagnose the radio. Run ados pair --role gs on the ground station and ados pair --role drone on the aircraft. See WFB-ng pairing.
Also confirm both ends are on the same channel, and that a pinned operating region is not excluding the channel one of them is trying to use. See Regulatory.

Video is black

Video crosses several stages, and each one fails differently. Start at the source and work outward rather than guessing.
It samples the counters at each hop twice and names the hop where video stops, so read that name before changing anything.
If the radio link is unverified, video will be black on the ground with a pipeline that is working on the aircraft. Confirm the link before investigating the camera, because the two symptoms are indistinguishable from the receiving end.
On a ground station driving an HDMI panel, a black panel with a healthy link is a display-side fault rather than a video-pipeline one. Check that the browser process is running, not just the unit that supervises it.

Repairing without reinstalling

Try these before a reflash. Each is idempotent. A half-finished install leaves checkpoints behind and can be resumed rather than restarted:
An out-of-date or partially broken install is repaired by ados update, which re-runs the installer in upgrade mode. It keeps identity and configuration:
A radio that will not come up may be missing its driver:

Factory reset

A factory reset deletes every credential, the device ID, the configuration, and the logs, so the box comes back up as if it were new. It does not reinstall software. The two reset paths, their gates, and the full list of what each deletes are on Operator hardening.

Reflash and reinstall

This is the supported recovery for a box that is broken, and it is deliberately not a repair-in-place procedure.
Do not fix a broken node by editing files under /opt/ados, /etc/ados, or the systemd units. A patched runtime cannot be reproduced, does not survive the next update, and turns the next fault into an investigation of unknown state. Read-only inspection of those paths is fine. Changing them is not.Recovery is a clean image plus a fresh install from a known release. That gets you a node whose state you can reason about.
  1. Collect evidence first, if the box still answers at all. Run ados support-bundle. Once you reflash, whatever caused the fault is gone. See Support escalation.
  2. Write a clean OS image to the card or eMMC, following Install the Drone Agent.
  3. Install the agent. On a drone:
    On a ground station, pass the profile explicitly so the box cannot come up as the wrong kind of node:
    To set the hostname you will reach the node by as <hostname>.local, pass --name <hostname> to the installer (sudo bash -s -- --name <hostname>, alongside --profile on a ground station). Every installer flag is listed on Install the Drone Agent.
  4. Re-pair. Pairing keys, radio keys, and the AP passphrase were on the old install and are gone. Pair the drone and ground station again, and re-pair Mission Control. See Pairing.
  5. Verify before flying. ados for overall status, ados diag link for the radio, ados diag video for the pipeline. Then work the pre-flight checklist in Safety.

Removing the agent

Next steps

Support escalation

Collect a bundle and report a fault.

Troubleshooting by area

Symptom guides for each product.

Operator hardening

What the credentials you just recreated grant.
Last modified on October 11, 2026