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

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:

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

Then configure portproxy and firewall from Administrator 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

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