Troubleshooting

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 streaming requires the Android Debug Bridge (ADB) tool to be present on your Mac. Install it with:

brew install android-platform-tools

In addition, enable Developer Mode on your Quest headset.

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

If you are on USB, verify the cable is a data cable (not charge-only). Many cables bundled with chargers do not carry data.

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.

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

Make sure the ALVR app is open and actively streaming on the headset before you launch the game from MoltenVR.

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:

game/hlvr/cfg/bindings_touch.json

MoltenVR routes game audio into the stream via BlackHole, a virtual audio loopback driver. Install BlackHole 2ch if it is not already present:

brew install --cask blackhole-2ch

Then go to System Settings → Privacy & Security → Microphone and confirm MoltenVR has permission.

MoltenVR uses switchaudio-osx to automatically redirect audio output to BlackHole when streaming starts. Install it with:

brew install switchaudio-osx

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.

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.

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.

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.