08. Troubleshooting

1. /admin returns Invalid url

Most common causes:

1. port conflict,
2. admin is running on a different port than expected,
3. reverse proxy path/port mismatch.

Check:

1. which process listens on admin port,
2. AdminPort and WebServerPort values in config,
3. curl -I http://<host>:<admin-port>/admin after restart.

2. Radar works locally but not on LAN

Check:

1. Network Binding is set to all interfaces,
2. host firewall rules,
3. service is listening on 0.0.0.0:<port>.

Linux example:

ss -ltnp | rg ':8080|:5000|:8085'
curl -I http://<lan-ip>:<port>/admin

3. AircraftList.json becomes empty after some time

Possible causes:

1. feed connection loss,
2. background exception stopping host,
3. overload or unstable upstream data patterns.

Check:

1. service logs (journalctl -u vrsx),
2. feed status and message throughput,
3. process uptime after errors.

4. Aircraft positions jump backward or flicker

Common causes:

1. MLAT instability,
2. low-quality feed or high jitter,
3. mixed sources without stable source-priority logic.

Diagnostic flow:

1. compare same feed in VRS X vs reference VRS,
2. test single feed instead of All feeds,
3. compare JSON output over identical bbox/time intervals.

5. Resource import says success, but no visual effect

1. Verify Loaded counters.
2. Verify CSV keys match asset names.
3. Clear browser cache.
4. Verify icon/type mapping and metadata consistency.

6. Map controls show strange outer frames in Futuristic / OverFuture

Symptoms:

1. zoom/layer/location control groups have extra rectangular outlines around button stacks.

Recovery steps:

1. perform hard refresh (Ctrl+Shift+R or Cmd+Shift+R),
2. clear site cache and reload,
3. verify the active theme is really Futuristic or OverFuture,
4. if issue persists, redeploy frontend static assets and refresh again.

7. Mobile aircraft detail sheet does not collapse/expand as expected

Check:

1. sheet can expand by tapping handle or swiping up,
2. collapse gesture works only when detail content scroll is at top,
3. after closing selected aircraft and reopening, sheet should start collapsed.

8. Bottom sheet is clipped by device home indicator (mobile)

Check:

1. confirm frontend HTML uses viewport meta with viewport-fit=cover,
2. clear browser cache so updated CSS safe-area rules are applied,
3. retest on real device (some desktop emulators do not reproduce full safe-area behavior).

9. Marker colors from Aircraft Colors / Operator Colors are not visible

Check:

1. Color by operator is enabled in label settings,
2. mapping key format is valid (ICAO hex for Aircraft Colors, operator code for Operator Colors),
3. if both mappings exist, remember Aircraft Colors override Operator Colors,
4. emergency or selected marker style can temporarily override normal tint.

10. Custom operator logo upload is rejected or not used

Common causes:

1. invalid proportions (must be 17:4),
2. image is too small for template (85x20 minimum for downscale path),
3. existing logo conflict with overwrite disabled,
4. invalid operator/type key format.

Check:

1. upload with naming rule OPERATOR or OPERATOR-ICAOTYPE,
2. if prompted, use explicit downscale to 85x20,
3. confirm OperatorFlagsList.csv and resource status are updated,
4. refresh browser cache and verify with specific aircraft type.

11. AircraftDB Editor shows duplicate ICAO conflict

Symptoms:

1. save returns conflict and message that aircraft already exists.

Expected behavior:

1. app prevents duplicate ModeS rows,
2. editor shows Load existing aircraft action for the conflicting ICAO.

Resolution:

1. load existing record,
2. apply edits there,
3. save update instead of creating a second record.

12. Custom aircraft photo upload succeeds but detail still shows fallback image

Check:

1. ICAO in editor is valid and matches the aircraft (6 hex chars),
2. custom photo status in editor shows custom photo available,
3. hard refresh detail panel to bypass stale browser cache,
4. if needed, delete and re-upload photo (system keeps only one custom photo variant per ICAO).