# 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:

```bash
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).