Most MoltenVR issues fall into one of five categories: streaming and connection problems, games not launching in VR, missing audio, macOS permission denials, and license expiry. Work through the relevant section below to resolve your issue.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/112cxyz/MoltenVR-Preview/llms.txt
Use this file to discover all available pages before exploring further.
Streaming & Connection
Headset is not connecting
Headset is not connecting
Check the following in order:
- Confirm the ALVR client v20.14.0 is installed on your headset. Other versions are not guaranteed to be compatible with MoltenVR’s streaming core.
- For Wi-Fi streaming: make sure both your Mac and headset are on the same network. A 5 GHz or 6 GHz band is strongly recommended.
- For USB streaming: confirm the cable is plugged in at both ends, then check the USB troubleshooting entry below.
- Make sure you press Start Stream in MoltenVR before opening the ALVR app on the headset.
USB connection not detected
USB connection not detected
USB streaming requires the Android Debug Bridge (ADB) tool to be present on your Mac. Install it with:In addition, enable Developer Mode on your Quest headset.
High latency on Wi-Fi
High latency on Wi-Fi
- Move closer to your router to improve signal strength.
- Connect both your Mac and headset to a 5 GHz or 6 GHz band. Avoid 2.4 GHz.
- For a stable baseline, try USB streaming — 100 Mbps over cable eliminates Wi-Fi jitter entirely.
Stream keeps dropping
Stream keeps dropping
If you are on USB, verify the cable is a data cable (not charge-only). Many cables bundled with chargers do not carry data.
Games & VR
Game launches flat (not in VR)
Game launches flat (not in VR)
The game is launching but not entering VR mode. This usually means it is using an OpenXR extension that MoltenVR’s runtime does not yet advertise. Open a GitHub issue at github.com/112cxyz/MoltenVR-Preview/issues with the name of the game — these are typically quick fixes.
Game crashes on launch
Game crashes on launch
A crash immediately after launch usually means the Wine bottle is missing required components. Re-run the setup wizard to ensure both of the following are installed into the bottle:
- DXMT — the D3D11→Metal graphics translation layer
- OpenXR VR runtime — the MoltenVR OpenXR runtime
Controllers are not being tracked
Controllers are not being tracked
Make sure the ALVR app is open and actively streaming on the headset before you launch the game from MoltenVR.
Half-Life: Alyx — controller bindings are wrong or cannot be rebound
Half-Life: Alyx — controller bindings are wrong or cannot be rebound
Half-Life: Alyx runs through OpenComposite, which translates SteamVR calls onto the MoltenVR OpenXR runtime. OpenComposite does not provide a SteamVR dashboard, so the in-game rebinding UI is unavailable.To change controller bindings, edit the bindings file directly:
Audio
No game audio in the headset
No game audio in the headset
MoltenVR routes game audio into the stream via BlackHole, a virtual audio loopback driver. Install BlackHole 2ch if it is not already present:Then go to System Settings → Privacy & Security → Microphone and confirm MoltenVR has permission.
BlackHole is installed but audio is still not working
BlackHole is installed but audio is still not working
MoltenVR uses
switchaudio-osx to automatically redirect audio output to BlackHole when streaming starts. Install it with:macOS Permissions
Screen Recording permission denied
Screen Recording permission denied
MoltenVR requires Screen Recording access to power the desktop view feature. To grant it, open System Settings → Privacy & Security → Screen Recording and enable the toggle for MoltenVR.
Microphone permission denied
Microphone permission denied
MoltenVR requires Microphone access to capture the BlackHole virtual audio device and route game audio into the stream. To grant it, open System Settings → Privacy & Security → Microphone and enable the toggle for MoltenVR.
macOS says MoltenVR is from an unidentified developer
macOS says MoltenVR is from an unidentified developer
MoltenVR is not yet notarized by Apple. On the first launch, macOS will block it with a Gatekeeper warning. To open it anyway, right-click (or Control-click) MoltenVR.app in Finder and select Open.
License & Preview
The 7-day preview has expired
The 7-day preview has expired
When the preview window closes, MoltenVR will ask for a license key on next launch. You have two options:
- Enter a license key — obtain one from Patreon (coming soon) to unlock the latest version of MoltenVR on this Mac.
- Download a fresh preview release — grab the latest release from GitHub Releases. Each new preview release resets the 7-day window.
If your issue isn’t covered here, get help from the community on Discord or file a bug report on GitHub Issues.