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

This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. If the Windows forwarding rule must stay, use a different Planet backend port.

If the script prints `failed-stop-service` or `failed-stop-process`, the current shell does not have permission to clear the Windows listener. Startup stops immediately instead of launching the backend into the same port conflict.

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

Then verify from Windows PowerShell:

```powershell
curl http://localhost:3000
curl http://localhost:8000/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 forwarding or firewall policy rather than Vite or `.zshrc`.

For traditional WSL NAT networking, configure portproxy and firewall from Administrator PowerShell:

```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
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
```

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
```

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. 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.

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