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:

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

First try:

./planet.sh restart -b

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

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

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:

netsh interface portproxy show all

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

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:

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

For temporary troubleshooting, you can stop IP Helper from Administrator 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. New --allow-lan runs a temporary Windows relay for 3000 / 8000, so persistent portproxy is no longer required.

If the script prints failed-stop-service, failed-stop-process, or Vite reports Port 3000 is already in use followed by Windows listener ... services=iphlpsvc, an old Windows listener still owns the port. Startup stops immediately and prints the recovery order: use Administrator PowerShell to 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; the script starts temporary relays while LAN devices still use 3000 / 8000.

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:

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

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

Then verify from Windows 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:

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

./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, ./planet.sh start --allow-lan starts temporary Windows relays so Windows still exposes 3000 / 8000. Before startup, the script checks for stale portproxy rules and requests Administrator PowerShell to delete them. It also checks Windows Firewall and, when inbound allow rules for 3000 / 8000 are missing, triggers a UAC Administrator PowerShell request to create them. If the automatic request is canceled, clean up manually:

netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=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

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:

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:

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:

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:

uv add mediapipe opencv-python

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

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:

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:

export KEY=value
KEY=value

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

PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a

To ignore ~/.zshrc while troubleshooting:

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:

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

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

ls /dev/video*

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

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

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

./planet.sh health

Then inspect logs:

./planet.sh log

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

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

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.