| pip install shows "error: externally-managed-environment" | Ubuntu protects the system Python environment according to PEP 668 | Install the application in an isolated environment with pipx install live-vlm-webui as shown in Step 2 |
| Browser shows "Your connection is not private" warning | Application uses self-signed SSL certificate | Click "Advanced" → "Proceed to <IP> (unsafe)" - this is safe and expected behavior |
| Camera not accessible or "Permission Denied" | Browser requires HTTPS for webcam access | Ensure you're using https:// (not http://). Accept self-signed certificate warning and grant camera permissions when prompted |
| "Failed to connect to VLM" or "Connection refused" | Ollama or VLM backend not running | Verify Ollama is running with curl http://localhost:11434/v1/models. If not running, start with sudo systemctl start ollama |
| VLM responses are very slow (>5 seconds per frame) | Model too large for available VRAM or incorrect configuration | Try a smaller model (gemma3:4b instead of larger models). Increase Frame Processing Interval to 60+ frames. Reduce Max Tokens to 100-200 |
| GPU stats show "N/A" for all metrics | NVML not available or GPU driver issues | Verify GPU access with nvidia-smi. Ensure NVIDIA drivers are properly installed |
| "No models available" in model dropdown | API endpoint incorrect or models not downloaded | Verify API endpoint is http://localhost:11434/v1 for Ollama. Download models with ollama pull gemma3:4b |
| Server fails to start with "port already in use" | Port 8090 already occupied by another service | Stop the conflicting service or use --port flag to specify a different port: live-vlm-webui --port 8091 |
| Cannot access from remote browser on network | Firewall blocking port 8090 or wrong IP address | Verify firewall allows port 8090: sudo ufw allow 8090. Use correct IP from hostname -I command |
| Video stream is laggy or frozen | Network issues or browser performance | Use Chrome or Edge browser. Access from a separate PC on the network rather than locally. Check network bandwidth |
| Analysis results in unexpected language | Model supports multilingual and detected language in prompt | Explicitly specify output language in prompt: "Answer in English: describe what you see" |
| pipx install fails with dependency errors | The existing pipx environment may be incomplete or outdated | Recreate the isolated environment with pipx uninstall live-vlm-webui && pipx install live-vlm-webui |
Command live-vlm-webui not found after install | The pipx application directory is not in PATH | Run pipx ensurepath, then start a new terminal or run source ~/.bashrc |
| Camera works but no VLM analysis results appear, browser shows InvalidStateError | Accessing via SSH port forwarding from remote machine | WebRTC requires direct network connectivity and doesn't work through SSH tunnels (SSH only forwards TCP, WebRTC needs UDP). Solution 1: Access the web UI directly from a browser on the same network as the server. Solution 2: Use the server machine's browser directly. Solution 3: Use X11 forwarding (ssh -X) to display the browser remotely |
