Skip to content

Troubleshooting

This page gives symptom-to-fix checks for common field problems. Each section lists likely causes and specific checks. Most checks use the web console and do not require a shell.

Two tools solve most cases

  • Sensor services card (Cockpit > AryaOS Site) lists the running gateways.
  • Support bundle (Cockpit > AryaOS Site > Support bundle, or sudo aryaos-support-bundle) captures redacted logs, service status, and config for support. See Support bundles.

No tracks in TAK

Aircraft, vessels, or drones are not appearing on the TAK map.

Most common cause: the TAK client is not on Mesh SA

AryaOS sends tracks to the Mesh SA multicast group 239.2.3.1:6969 by default. Your ATAK/WinTAK/iTAK device must be joined to the AryaOS hotspot and have Mesh SA enabled to receive them.

Check, in order:

  1. Is the TAK client on the right network? Confirm the phone/laptop is joined to AryaOS-xxxx, not another Wi-Fi.
  2. Is Mesh SA enabled in the TAK client? In ATAK, enable the Mesh SA / multicast input.
  3. Is the sensor running? Open the Sensor services card. The relevant gateway must be active.
  4. Is the right role selected? The device role must include your sensor - e.g. air or multi for aircraft. Set it in the Device role card.
  5. Is the radio decoding? For ADS-B, the aircraft feed lives at /run/adsb/aircraft.json. If it is empty, the SDR or antenna is the problem (see SDR not detected).

See Aircraft (ADS-B), Maritime (AIS), Counter-UAS.

Cannot reach the web console

https://aryaos-xxxx.local or 10.41.0.1 will not load.

  1. Give first boot time. A new device needs ~120 seconds before the hotspot and web console come up.
  2. Are you on the hotspot? Join AryaOS-xxxx first.
  3. Try the IP. If aryaos-xxxx.local fails (mDNS resolver issue), use https://10.41.0.1.
  4. Accept the certificate. The per-device certificate is self-signed. The browser warning is expected - proceed. See Security posture.
  5. Try the direct Cockpit port. The portal proxies 443 > Cockpit. You can also reach Cockpit directly on https://<host>:9090.
  6. Firewall. If you changed the firewall, confirm Cockpit/portal are still allowed in Firewall.

No Wi-Fi hotspot

The AryaOS-xxxx network never appears.

  1. Wait out first boot (~120 s on a new device).
  2. Confirm the suffix. The SSID is AryaOS-xxxx where xxxx matches the hostname. Look carefully - it can not be the name you expect. See DEVICE_SUFFIX.
  3. Already joined to another Wi-Fi? comitup runs the hotspot only when not connected as a client. If the box joined a known network, the AP can be down by design. See Wi-Fi & onboarding hotspot.
  4. Reach it another way. Connect over Ethernet or the Bluetooth PAN to investigate.

SDR not detected

A radio is plugged in but the decoder sees nothing.

  1. List the dongles. In Radios (or sudo aryaos-sdr list) confirm the dongle enumerates.
  2. Check the serial. Each SDR needs a unique serial. stx:1090:0 for ADS-B, stx:978:0 for UAT. Two dongles with the same serial collide. Fix with Radios or aryaos-sdr set-serial, then replug or reboot.
  3. Power. Multiple SDRs can exceed the Pi's USB budget - use a powered hub and a stronger power supply. See Hardware & requirements.
  4. Antenna. No detections despite a working dongle usually means an antenna/placement problem - check the connector and line of sight.

Box keeps rebooting, or all sensors are stopped (safe mode)

If the box repeatedly reboots, an inadequate power supply is the likely cause. AryaOS enters safe mode to remain reachable. Safe mode stops sensors and turns off USB peripherals.

  1. Confirm. Run aryaos-safe-mode status, or find the red banner on the AryaOS Site page. safe-mode: ON with a crash-loop reason means three short boots triggered it.
  2. Fix the power - nearly always the cause. See Power & battery. A Pi 5 needs a 5V/5A (27 W) supply. A big GaN charger that only does 5V/3A, or a PoE HAT on plain 802.3af, will not sustain it.
  3. Restore. On a good supply, clear safe mode from Cockpit > AryaOS Site > Safe mode ("Restore now" or "Restore & reboot"), or sudo aryaos-safe-mode off - this re-powers USB and restarts the sensors.
  4. Check under-voltage any time with vcgencmd get_throttled (0x0 is clean). The AryaOS Site page also shows this as a live power-health warning.

A service will not start

A gateway shows as failed or keeps restarting.

  1. Sensor services card - identify which unit is down.
  2. Read the logs. The support bundle includes each service's recent journal. Generate one from Support bundle (or sudo aryaos-support-bundle), which redacts secrets automatically. See Support bundles.
  3. Check the role. A unit disabled by the current device role is expected to be stopped. That is not a failure. Switch roles in Device role if you need it running.
  4. From a shell (optional): systemctl status <unit> and journalctl -u <unit> show the failure reason.

TAK Server will not connect

Tracks reach Mesh SA but not your TAK Server.

  1. Re-import the connection. Import the TAK data package or tak:// enrollment link again from the TAK connection card. AryaOS installs the certs and writes a COTBridge lane. See Connect to a TAK Server.
  2. Certificate/CA. A bad or expired client certificate, or the wrong CA in the package, stops the TLS handshake. Get a fresh package from your TAK admin.
  3. Reachability. The device must be able to reach the server host and port (the connect string in the package). On a disconnected box, add a route. Ethernet, an upstream Wi-Fi client connection, or the VPN.
  4. COTBridge lane. Confirm the lane:site-output lane is enabled and its egress URL names the intended server in the COTBridge lane editor.

A current gateway does not exit just because the server, route, or local firewall is temporarily unavailable. PyTAK 7.5.2 and the reconnect-safe custom clients keep the same process alive, report retrying or degraded, and retry forever with a bounded backoff. When connectivity returns, the gateway creates a fresh transport and resumes sending without a service restart.

Check that behavior while an outage is in progress:

systemctl show <gateway>.service -p ActiveState -p MainPID -p NRestarts
sudo aryaos-health status --json
journalctl -u <gateway>.service --since '-15 minutes'

ActiveState=active, an unchanged nonzero MainPID, and NRestarts=0 are the expected outage state. The health output must move back to ok and connected after recovery, with receive or emit counters increasing when the sensor has data. A permanent configuration error, unreadable certificate, bad enrollment package, or rejected TLS identity is not transient. Correct that input instead of expecting retries to repair it.

GPS has no fix

The device's own position is missing or wrong.

  1. Is the puck detected? GPS uses gpsd. Confirm the USB GNSS receiver is recognized (the support bundle captures a gpsd snapshot).
  2. Sky view. GNSS needs a clear view of the sky. A cold start can take minutes indoors or under cover.
  3. Is the position gateway running? gpscot/lincot publish position. Both are part of the always-on CoT core. Check the Sensor services card. See Own position (GPS).

Still stuck?