Repository navigation
Troubleshooting
This page covers common issues when installing, launching, and using VRViewer.
If your issue isn't covered here, open a bug report.
Before reporting a problem, make sure you're using the latest version of VRViewer and review the relevant steps below.
- VRViewer won't launch
- The viewer displays a black screen
- OpenXR source isn't working
- SteamVR source isn't working
- The image is incorrect or distorted
- VRViewer crashes or freezes
- Performance or latency problems
- Installation or update problems
- Collecting information for a bug report
If VRViewer fails to open or closes immediately:
- Confirm that your Windows version meets the application's system requirements.
- If Windows displays a security warning, verify that you downloaded the installer from an official LTM Technologies source before proceeding.
- Try launching VRViewer again and note any error message.
- If the problem began after an update, note the previous and current versions.
- Restart Windows if the application or a related VR runtime appears stuck.
If the application still won't launch, open a bug report and include the error message, VRViewer version, and relevant logs.
A black screen can indicate that the selected source isn't producing an image or that the source hasn't initialized successfully.
- Confirm that the application or VR runtime you're trying to capture is running.
- Open VRViewer and check which source is selected.
- If another source is available, select it to help determine whether the problem is specific to one source.
- Close and reopen VRViewer, then try again.
- Note whether the viewer remains black, displays an error, or begins working after switching sources.
When reporting this issue, include the selected source, the VR runtime in use, and whether the problem occurs with every source or only one.
If the OpenXR source doesn't initialize or display an image:
- Confirm that your intended OpenXR runtime is installed and functioning.
- Launch the VR application you want to view and verify that it works normally.
- Check whether the problem affects all OpenXR applications or only one.
- Record the name and version of the active OpenXR runtime.
- Restart the affected application and VRViewer, then test again.
If the problem persists, include your headset, OpenXR runtime, runtime version, and any error messages in your report.
If the SteamVR source doesn't initialize or display an image:
- Confirm that SteamVR is installed and launches successfully.
- If your setup requires a headset or an active VR session, verify that it is connected and running.
- Launch the VR application and confirm that SteamVR is operating normally.
- Restart SteamVR and VRViewer, then try selecting the SteamVR source again.
- Record any error messages and whether SteamVR reports that the headset or server is unavailable.
Some errors may depend on how SteamVR is configured and whether a usable VR session is active.
If the image appears stretched, cropped, incorrectly positioned, or otherwise distorted:
- Record which source is being used.
- Check whether the problem occurs in every application or only one.
- If you're using custom presentation or stereo-blending settings, note those settings.
- If possible, return to your previous known-working configuration and test again.
- Capture a screenshot of the issue, if doing so is practical.
For stereo-blending issues, include the relevant overlap, blend position, and blend width values, if applicable.
Avoid changing multiple settings at once. Changing one setting at a time makes it easier to identify the cause.
If VRViewer stops responding or closes unexpectedly:
- Record what you were doing immediately before the problem occurred.
- Note whether the crash happens at startup, while switching sources, or during normal viewing.
- Check whether the problem can be reproduced consistently.
- Restart VRViewer and the affected VR runtime.
- If the issue continues, capture any error message or relevant Windows crash information.
If the entire PC restarts or shuts down, mention that explicitly. A whole-system restart is different from an application-only crash.
If VRViewer or your VR experience becomes slow, stutters, or develops increased latency:
- Check whether the problem occurs continuously or only at specific times.
- Close unnecessary applications and background recording or streaming tasks for a comparison test.
- Check whether the issue occurs with one source or multiple sources.
- Record your GPU, headset, VR runtime, and any relevant capture or streaming software.
- If you use performance overlays, include the measurements that change when the issue occurs.
Describe whether the problem affects VRViewer's displayed image, the underlying VR application, or both.
If installation fails or an update doesn't work as expected:
- Verify that you downloaded the installer from an official source.
- Record the installer version and any error messages.
- Check whether VRViewer is currently running and close it before trying the installation again.
- If the problem began after an update, record the previous and new versions.
- Do not delete application data or configuration files as a troubleshooting step unless instructed to do so.
If the installer fails repeatedly, include the Windows version and the exact error message in your report.
If none of the steps above resolves your issue, submit a bug report.
Please include as much of the following information as you can:
- VRViewer version: The version you're running.
- Windows version: Your Windows edition and version.
- Headset: The VR headset you use, if applicable.
- OpenXR runtime: The active runtime, if applicable.
- SteamVR version: If SteamVR is involved.
- Selected source: OpenXR, SteamVR, Test, or another available source.
- Steps to reproduce: The sequence of actions that triggers the issue.
- Expected behavior: What you expected to happen.
- Actual behavior: What happened instead.
- Logs and screenshots: Relevant errors or evidence, with sensitive information removed.
GitHub issues in this repository are public. Do not post passwords, license keys, private access tokens, personal information, or unredacted logs containing sensitive data.
If you're unsure whether a log is safe to share, describe the error first and ask before posting the full file.
Thank you for helping improve VRViewer!