planet/docs/technical/en/faq.md

# FAQ

This page collects common troubleshooting paths for local startup, Windows / WSL, dependencies, motion capture, credentials, and Docs permissions. Deeper background stays in the topic-specific docs; this page focuses on what to check first and which command to run.

## Startup and Ports

### What should I do when the backend port is already in use?

The error usually looks like:

```text
Backend address is already in use: 0.0.0.0:8000 / 127.0.0.1:8000 / [::1]:8000
Address already in use
```

First try:

```bash
./planet.sh restart -b
```

If the port remains occupied, start on a different backend port:

```bash
./planet.sh start -b 8001
```

In WSL, the listener may be on the Windows side rather than a Linux process. A common diagnostic line looks like:

```text
Windows listener: 0.0.0.0:8000 pid=4700 process=svchost.exe services=iphlpsvc
```

`iphlpsvc` is the Windows IP Helper service. It often hosts IPv6, tunneling, proxying, port forwarding, WSL, or developer-tool networking features. Do not start by killing that `svchost.exe`; first check whether an old portproxy rule owns the port.

From Administrator PowerShell, inspect portproxy rules:

```powershell
netsh interface portproxy show all
```

If you see `0.0.0.0:8000` or `listenport=8000`, delete that rule:

```powershell
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
```

If there is no portproxy rule, confirm which services are hosted by that PID:

```powershell
netstat -ano | findstr :8000
tasklist /svc /fi "PID eq 4700"
```

For temporary troubleshooting, you can stop IP Helper from Administrator PowerShell:

```powershell
Stop-Service iphlpsvc -Force
```

This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. `--allow-lan` now binds `3000` / `8000` / `8010` directly, so persistent portproxy is no longer required.

If the script prints `Windows 侧端口 ... 存在监听者`, or Vite reports `Port 3000 is already in use` followed by `Windows listener ... services=iphlpsvc`, an old Windows listener still owns the port. The script requests Administrator PowerShell cleanup for that port. If the automatic cleanup is canceled, inspect `netsh interface portproxy show all`, delete the matching `listenport` rule, confirm the PID and services with `netstat` / `tasklist` if no portproxy rule exists, and temporarily run `Stop-Service iphlpsvc -Force` when appropriate. After old rules are gone, rerun `./planet.sh restart --allow-lan`; LAN devices still use `3000` / `8000` / `8010`.

### Which startup flags change default ports?

| Service | Default port | Flag |
| --- | --- | --- |
| Frontend | `3000` | `-f <port>` |
| Backend | `8000` | `-b <port>` |
| AI Provider | `8010` | `-a <port>` |
| Motion Agent | `8765` | `--motion-agent-port <port>` |

Example:

```bash
./planet.sh start -f 3001 -b 8001 -a 8101
```

## Windows / WSL / LAN

### LAN access does not work on Windows / WSL. What should I check?

Check in this order before changing firewall rules:

```bash
# In WSL or the shell running Planet
curl http://localhost:3000
curl http://localhost:8000/health
curl http://localhost:8010/health
```

Then verify from Windows PowerShell:

```powershell
curl http://localhost:3000
curl http://localhost:8000/health
curl http://localhost:8010/health
```

If both localhost checks pass but a phone or another computer cannot connect, start with LAN enabled:

```bash
./planet.sh start --allow-lan
```

The flag must be written as `--allow-lan`. `allowlan` or `--allowlan` is not recognized by the startup script. If Planet is already running and you only need to reopen the frontend on the LAN, restart the frontend explicitly:

```bash
./planet.sh restart -f 3000 --allow-lan
```

If `ss -ltnp` shows the frontend listening on `0.0.0.0:3000`, but `Test-NetConnection <Windows LAN IP> -Port 3000` still fails from Windows PowerShell, the problem is usually Windows-side port ownership, stale `portproxy`, or firewall policy rather than Vite or `.zshrc`.

`./planet.sh start --allow-lan` directly exposes `3000` / `8000` / `8010` and checks port availability, stale `portproxy`, and Windows Firewall before startup. If a Windows-side listener owns a port, the script requests Administrator PowerShell cleanup. When inbound allow rules are missing, it also triggers a UAC Administrator PowerShell request to create them. If the automatic request is canceled, clean up manually:

```powershell
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010

New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010
```

LAN devices should use the Windows external port, for example `http://<Windows LAN IP>:3000/earth`.

If `wslinfo --networking-mode` prints `mirrored`, also check Hyper-V firewall. Even when ordinary Windows Firewall rules exist, Hyper-V firewall can still block external devices from reaching WSL. From Administrator PowerShell, allow the required ports:

```powershell
New-NetFirewallHyperVRule -Name "Planet-Frontend-3000" -DisplayName "Planet Frontend 3000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 3000 -Action Allow
New-NetFirewallHyperVRule -Name "Planet-Backend-8000" -DisplayName "Planet Backend 8000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8000 -Action Allow
New-NetFirewallHyperVRule -Name "Planet-AIProvider-8010" -DisplayName "Planet AI Provider 8010" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8010 -Action Allow
```

Use these commands to inspect the current Hyper-V firewall state:

```powershell
Get-NetFirewallHyperVVMSetting -Name "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}"
Get-NetFirewallHyperVRule -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}"
```

LAN devices should open the Windows LAN IP, for example `http://<Windows LAN IP>:3000/earth`, not the internal WSL IP.

### How do `--allow-lan` and the Motion Agent LAN URL fit together?

`--allow-lan` binds the frontend, backend, and optional Motion Agent to `0.0.0.0`. If a remote browser needs to connect to the display machine's Motion Agent, pass the Agent URL explicitly:

```text
http://<LAN_IP>:3000/earth?motion=1&motionProvider=agent&motionAgent=ws://<LAN_IP>:8765/ws/gestures
```

Browser Camera mode does not need a `motionAgent` URL.

## Dependencies and Environment Variables

### Why should I use `uv` instead of `pip`?

Planet manages Python dependencies through `uv` and `pyproject.toml`. Avoid `pip install` in the project environment, because it can diverge from the lock file and startup scripts.

For Motion Agent live dependencies, use:

```bash
uv add mediapipe opencv-python
```

`planet.sh start --motion-agent` checks and installs those live dependencies automatically. To disable auto-install:

```bash
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
```

### Why should I use `bun` instead of `npm run`?

The frontend runtime is Bun. This avoids WSL / Windows mixed-path issues that can happen when npm invokes `cmd.exe`.

Common commands:

```bash
bun install
bun run dev
bun run build
```

If a non-interactive shell cannot find `bun`, `planet.sh` searches the current PATH, `~/.bun/bin`, zsh config, and PowerShell command resolution.

### When does `planet.sh` read environment variables from `.zshrc`?

By default, `planet.sh` statically parses simple lines in `~/.zshrc`:

```bash
export KEY=value
KEY=value
```

This avoids slow shell themes, plugins, and interactive initialization. For complex shell expansion, opt in to source mode:

```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```

To ignore `~/.zshrc` while troubleshooting:

```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```

Never put real secret values in docs or commits; documentation should only mention variable names and purposes.

## Motion Capture / Cameras

### Does Browser Camera mode need the `motionAgent` parameter?

No. Browser Camera mode uses webpage `getUserMedia` and runs recognition locally in the browser.

Recommended URL:

```text
/earth?motion=1&motionProvider=browser
```

You can also open Earth settings, enable Motion Debug Mode, and select Browser Camera as the input source. The page must run on HTTPS or localhost, and the user must grant browser camera permission.

### When do I need Motion Agent?

Use Motion Agent for:

- dual USB cameras
- RTSP / HTTP camera streams
- edge devices or client integration
- a standalone local recognition service

Common commands:

```bash
./planet.sh start --motion-agent
./planet.sh start --motion-agent --motion-agent-camera-indexes 0,1
./planet.sh start --motion-agent --motion-agent-camera-urls rtsp://example/live
./planet.sh start --motion-agent --motion-agent-dry-run
```

`--motion-agent-dry-run` is only for protocol and frontend connection testing; it does not open cameras.

### Why does WSL not find my camera?

Windows cameras usually do not appear inside WSL as `/dev/video*`. Check first:

```bash
ls /dev/video*
```

If no device appears, use Browser Camera for ordinary web demos. For Agent live mode, use an RTSP / HTTP camera URL:

```bash
./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
```

USB passthrough into WSL is an advanced path. The script does not silently downgrade missing-camera live mode to dry-run.

## Docker / AI Provider

### Why does changing the AI key, base URL, or model not rebuild the image?

Keys, base URLs, and model names are runtime configuration. They do not require a Docker image rebuild. Restart AI Provider:

```bash
./planet.sh restart -a
```

The first Docker build may be slow because of image layers or `uv sync` dependency downloads. Later builds reuse `.dockerignore`, BuildKit, and uv cache.

### What should I do when Docker health checks fail?

Start with:

```bash
./planet.sh health
```

Then inspect logs:

```bash
./planet.sh log
```

If only AI Provider is unhealthy, restart just that service:

```bash
./planet.sh restart -a
```

## Datasource and Collector Credentials

### Connectivity validation passes, but collection cannot read credentials. Why?

Connectivity validation can read saved console settings, environment variables, and some credentials from `~/.zshrc`. For actual collection, prefer saving credentials in Settings -> Collector Settings, especially for AISStream's long-lived WebSocket collector.

If `AISSTREAM_API_KEY` only lives in `~/.zshrc`, confirm the backend process actually inherited it. Otherwise validation may pass while the collector runtime has no key.

### Where should BarentsWatch / AISStream credentials live?

For temporary debugging, environment variables or `~/.zshrc` are fine:

```bash
export AISSTREAM_API_KEY="..."
export BARENTSWATCH_CLIENT_ID="..."
export BARENTSWATCH_CLIENT_SECRET="..."
```

For stable operation, save credentials in Collector Settings so connectivity validation, collection jobs, and Earth realtime aggregation use the same configuration.

## Docs / Permissions

### Why can I not see some Docs pages?

Docs visibility is controlled by Gatekeeper groups:

- Quickstart, Manual, FAQ, and other basic docs are public.
- Development docs usually require `docs_developer`.
- Operations and service-control docs usually require `docs_admin`.
- `admin` and `super_admin` have Docs access by default; ordinary users need groups assigned from the Users page.

## Earth Common Tasks

### Why did collecting a location candidate not write anything?

Collecting and saving are two separate actions. Candidates can be previewed on Earth first. A candidate is written only after clicking Save or using the unresolved list's one-click adopt flow.

Compute-center saves write to `compute_center_locations` and refresh the layer. Records with no candidate stay in the unresolved list; Planet does not fabricate a location from a country center or hard-coded hint.

### Why are satellites no longer on one sphere?

Earth enables "Real Satellite Altitude" by default. Satellite positions still come from TLE/SGP4, but altitude is compressed for display: LEO satellites stay close to the globe, while higher-orbit satellites render farther out without leaving the normal view. The maximum display offset is `25`, about one quarter of the current globe radius; this is a readability compromise that separates GEO / MEO / LEO without drawing real kilometers to scale. This setting also affects satellite trails and the predicted orbit shown after locking a satellite.

Turn off "Real Satellite Altitude" in Earth Settings to restore the legacy same-sphere satellite display. Satellites with missing TLE data or failed propagation still fall back to the legacy fixed height, so they do not disappear just because a real altitude cannot be computed.

Low-inclination high-orbit satellites should stay near the equator or a fixed longitude band, not form a near north-south ring. Earth converts the SGP4 inertial position to Earth-fixed coordinates for the current dot; the locked predicted orbit fixes the current globe pose and draws one inertial orbit, so it should close and preserve the correct inclination. If a future details card shows inclination near `0°` but the predicted orbit looks polar, check the ECI/TEME-to-ECF conversion and whether the predicted orbit accidentally uses per-sample `gstime`.

### Why does Motion Debug not show camera video?

With the Browser Camera source, the debug panel shows the local browser camera preview and draws the skeleton over it. If `Skeleton Only` is enabled, the video preview is hidden and the panel keeps only the dark canvas plus red/green skeleton.

With the Motion Agent source, the Agent WebSocket sends normalized joints, bones, and matched gestures only. It does not stream raw camera frames to Earth, which keeps privacy risk, bandwidth, and latency lower. In that mode the panel is a skeleton debug view rather than a video stream.