-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Common failure modes and what fixed them. Add an entry when you hit (and resolve) something new — this is the community knowledge buffer.
- Cable might be charge-only — USB-C cables look identical regardless of capability. Try a different cable known to do data.
- Quest must be awake. ADB can't see a sleeping headset. Press the power button or put it on briefly.
- Quest may not have authorized this PC yet. Put on the headset and accept the "Allow USB debugging?" dialog.
Inside VR, accept the "Allow USB debugging?" dialog. Tick "Always allow from this computer". If no dialog appears: go to Quest Settings → System → Developer → Revoke USB debugging authorizations, then run adb kill-server && adb devices — this re-triggers the dialog.
You opened the URL in the wrong place. Must be Quest Browser app (the native browser), not the Phone-mirror / Library / Casting window. Look for the standalone Browser icon in your App Library.
You loaded the page over plain HTTP from a LAN IP. Localhost-over-http counts as secure, LAN-over-http does not. Either:
- Switch to
https://with mkcert set up (see Cordless Setup mkcert HTTPS + Quest Cert Install), OR - Switch to
adb reverse+http://localhost:8000/vr(see Quick Start)
- The browser doesn't support WebXR in this context. Make sure you're in Quest Browser (not Firefox Reality, not some other Android browser sideloaded).
- Hand-tracking may be off in Settings. Settings → Movement Tracking → Hand and Body Tracking → On + Auto Switch.
- Server isn't running. Check that
openmuscle webis up in a console window on your PC. - Wrong port or IP in the URL. Double-check the LAN IP (PC's
ipconfig/ifconfig) matches what's in the headset's address bar. - Windows Firewall blocking inbound 8000. Allow it via the prompt that pops up on first inbound connection, or add a rule explicitly:
New-NetFirewallRule -DisplayName "OpenMuscle web (8000)" -Direction Inbound -Protocol TCP -LocalPort 8000 -Action Allow
Either the root CA isn't installed on the headset, or the cert doesn't include the IP/hostname you're using. Re-check Quest Cert Install and that your cert covers the exact URL you're visiting (mkcert's cert-file output lists which names it's valid for).
Quest Browser caches ES modules aggressively even with Cache-Control: no-store. The client uses a ?v=N querystring in the script src that bumps on every release; usually a refresh picks it up. If it doesn't, force a hard cache clear: three-dot menu in Quest Browser → Settings → Privacy → Clear browsing data.
Hand tracking isn't producing input. Most common cause: Quest is in controller mode. Set both controllers down on a flat surface (table, desk, floor — not held, not in your lap). Quest auto-switches to hand tracking within 2-5 seconds when controllers stop moving.
If still nothing: Settings → Movement Tracking → Hand and Body Tracking → On + Auto Switch.
The off-hand (the one NOT wearing the FlexGrid) is what drives the menu via raycast pointer. If you don't see it:
- Off-hand isn't being tracked. Hold it palm-up toward the headset's front cameras.
- You used the wrong
?arm=value in the URL.?arm=rightmeans right arm is the captured one and LEFT is the off-hand. Check your URL.
Known issue: with the v1.x AR scaling defaults, some users find panels still too big. Workarounds:
- Use the drag handles (top-left corner of each cluster) to move panels into your peripheral view rather than center.
- Use the RECENTER button in the menu to re-anchor panels to your current view direction (turn to face an unobtrusive direction first, then tap RECENTER).
- If still too big, file an issue — we may need to expose AR-scale as a URL param.
- Your off-hand ray must turn amber when it's over the button — that's the hover indicator. If the ray stays blue, you're not actually hovering it.
- Once amber, pinch (index + thumb touch) is the click. Quick pinch (not held). If the captured arm's pinch is registering instead, make sure you're pinching with the OFF hand.
- The hands-free fallback for REC only is pinch-and-hold on the captured arm for 1 second. A yellow ring on the index tip fills during the hold.
- Make sure PREDICT is enabled (red). The TRAIN button auto-enables it after a successful train, but you can toggle it manually.
- Need a model loaded. Tap TRAIN at least once after recording something.
- Need the captured hand visible to Quest's cameras — ghost is anchored to the real wrist position. If the wrist is out of view, ghost hides.
- FlexGrid isn't streaming. Check that the bracelet is powered and the OLED display shows it's connected to Wi-Fi.
- FlexGrid is on a different Wi-Fi network than the PC. They have to be on the same subnet for UDP to route.
- Firewall blocking inbound UDP 3141. Less common than the 8000 firewall issue since you usually hit it before the WebXR work, but possible.
- Quest WebSocket connection is dropping. Look at the desktop UI's log panel for
quest connected:/quest disconnected:lines. - Sensor and label rates are very different. The default match window for Quest (175ms) handles typical Quest latency. If you're seeing <30% match, something's off — file a Troubleshooting issue.
Hit something not covered here? Edit this page directly via the GitHub web UI — no PR needed. Format: short heading describing the symptom, then bullet-list of what fixed it (or what to check). Real failure modes from real sessions are far more useful than hypothetical ones.