From b12b42d3d8e20f6b65d1634629620073b57abc94 Mon Sep 17 00:00:00 2001
From: Loi Nguyen <loinguyen@local>
Date: Sun, 19 Jul 2026 19:23:14 +0700
Subject: [PATCH] docs: add WSL bridge troubleshooting

---
 docs/troubleshooting.md | 96 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 07157e93..cfad31d0 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -5,6 +5,102 @@ gives the cause and the exact fix. For full setup steps see
 [Installation](installation.md); for building from source see
 [Building from Source](contributing/building.md).
 
+## WSL: bridge cannot connect or dashboard cannot render
+
+The recommended WSL setup is to run Unreal Engine on Windows and run
+`urlab_bridge` inside WSL 2. Treat Windows and WSL as separate hosts:
+
+- Use the default ZMQ transport. Do not use `transport="shm"`; Windows and the
+  WSL virtual machine cannot share URLab's memory-mapped transport files.
+- Use WSLg for the `urlab-ui` window, its embedded MuJoCo renderer, and the
+  separate OpenCV camera windows.
+- Diagnose connectivity with `urlab-ping` before troubleshooting rendering.
+
+### Check the Windows connection
+
+Start the URLab bridge server in Unreal, then run this inside WSL:
+
+```bash
+uv run urlab-ping --address tcp://localhost
+```
+
+`localhost` works when WSL uses mirrored networking. The default WSL 2 NAT
+mode requires the Windows host address instead:
+
+```bash
+WINDOWS_HOST=$(ip route show default | awk '/default/ {print $3; exit}')
+uv run urlab-ping --address "tcp://$WINDOWS_HOST"
+```
+
+If the host address works only while Windows Firewall is disabled, add an
+inbound rule for URLab on private networks. Run PowerShell as Administrator:
+
+```powershell
+New-NetFirewallRule -DisplayName "URLab from WSL" `
+    -Direction Inbound -Action Allow -Protocol TCP `
+    -LocalPort 5555-5567 -Profile Private
+```
+
+The range includes RPC (`5559`), state (`5555`), control and discovery
+(`5556-5557`), and the dynamically allocated camera publishers (`5558-5567`).
+Keep using the same address with the dashboard:
+
+```bash
+uv run urlab-ui --host "tcp://$WINDOWS_HOST"
+```
+
+### Restore WSLg rendering
+
+If `urlab-ping` succeeds but `urlab-ui` fails with a GLFW, GLX, EGL, or
+`DISPLAY` error, update and restart WSL from PowerShell:
+
+```powershell
+wsl --update
+wsl --shutdown
+```
+
+Open a new WSL terminal and verify that WSLg supplied its display variables:
+
+```bash
+printf 'DISPLAY=%s\nWAYLAND_DISPLAY=%s\n' "$DISPLAY" "$WAYLAND_DISPLAY"
+```
+
+Both values should normally be non-empty. Remove old shell startup lines that
+manually export `DISPLAY`; they override WSLg's values. On Ubuntu, use
+`mesa-utils` to verify that OpenGL initializes before starting the dashboard:
+
+```bash
+sudo apt update
+sudo apt install mesa-utils
+glxinfo -B
+```
+
+Install the bridge UI extra, then use EGL for MuJoCo's offscreen renderer while
+WSLg owns the dashboard window:
+
+```bash
+uv sync --extra ui
+MUJOCO_GL=egl uv run urlab-ui --host tcp://localhost
+```
+
+If EGL reports `EGL_NOT_INITIALIZED`, retry with WSLg's GLFW backend:
+
+```bash
+MUJOCO_GL=glfw uv run urlab-ui --host tcp://localhost
+```
+
+As a diagnostic fallback for broken GPU passthrough, force Mesa software
+rendering. This is slower but distinguishes a graphics-driver problem from a
+URLab connection problem:
+
+```bash
+LIBGL_ALWAYS_SOFTWARE=1 MUJOCO_GL=glfw uv run urlab-ui --host tcp://localhost
+```
+
+If the dashboard opens but its Camera tab remains empty, confirm that the
+camera ports (`5558-5567`) are allowed through Windows Firewall and that camera
+streaming is enabled as described in [Sensors & Cameras](guides/sensors_cameras.md).
+
 ## Build error: submodule drift
 
 **Symptom.** The UE build fails with a message like: