Repository navigation
Troubleshooting
inksong edited this page Nov 9, 2026
·
2 revisions
| 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
|
| 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 |
| 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 |
| 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.
Get started
Simulation
- Simulator and Physics
- Collisions and Rings
- Firmware Twins and HITL
- PX4 and ArduPilot SITL
- Simulators Compared
Arena
Programs and agents
Tools
Help