Skip to content

Troubleshooting

inksong edited this page Nov 9, 2026 · 2 revisions

Troubleshooting

Installing and starting

Symptom What to do
Windows SmartScreen blocks the installer The installer is not code-signed yet: More info, then Run anyway. Check it against SHA256SUMS.txt first
The Linux AppImage does not start Install FUSE 2 (sudo apt install libfuse2 on Ubuntu 22.04 and later), or use the .tar.gz
The window stays on the opening film Any key skips it. If the backend failed, the window says so; the log is in the app data folder under logs/
Port 8765 is taken Relay uses the first free port from 8765 to 8775; SDK and MCP clients read RELAY_API

Aircraft

Symptom What to do
An aircraft does not appear Check that it sends to UDP 14550 on this computer and that the firewall allows it. Use Scan network, or Connect… with its address
A SITL aircraft on the same computer does not appear Start Relay with RELAY_ALLOW_LOOPBACK=1; see PX4 and ArduPilot SITL
Preflight reports that MAVLink input is not allowed PX4: COM_RC_IN_MODE 1 to 3. ArduPilot: MAV_GCS_SYSID / SYSID_MYGCS and RC_OVERRIDE_TIME
Unsteady after take-off Most often STABILIZE: fly altitude hold. Watch Flight health in the inspector; run hover_tune from Bench Procedures
Arming fails with "No manual control input" or "Throttle below failsafe" The autopilot sees no pilot input. Relay 0.5.3 sends centred zero-throttle sticks before every arm; update, or possess the aircraft before arming
Hovers but drifts steadily one way A level error or gyro bias: fly a timeline and cancel the drift with its trim
Sticks feel reversed Check stick directions with the propellers removed; per-axis inversion is in Settings → Controllers

Agents and programs

Symptom What to do
sticks_only (403) The agent flight level is Sticks only. Fly with sticks or a program, or let the operator choose Full in Settings → Safety
possessed_by_human A person is flying the aircraft. Wait for relay_handback
Application tools return a permission error Turn on Allow agents to operate Relay in Settings → Safety
A program ends as faulted Read its log: 25 faults or 3 frames past 15 ms in a row end it. Keep step light; a heavily loaded computer can also miss deadlines
A program will not deploy on a real aircraft Turn on Allow programs on this aircraft (confirm word PROGRAM) and pass preflight

Arena and dogfights

Symptom What to do
Terminals do not see each other Same broadcast domain, UDP 47114 open, no client isolation on the Wi-Fi network
A 0.4 terminal shows no statistics Collisions, matches and the leaderboard need 0.5 on both terminals; rounds and hits work with 0.4
dogfight_no_aircraft At most 8 simulators per terminal
dogfight_real_aircraft Real aircraft never take part; use simulators
Aircraft keep leaving the arena Programs have no arena position sensor unless the scenario provides one; widen arena.radius

Still stuck? Open an issue with the version, platform and the relevant part of the log.

Clone this wiki locally