Troubleshooting
The add-on not loading, a dashboard on WAITING, the cockpit not showing, passthrough edges.
Each problem lists what to check, in order. Most answers are in Settings › System.
The VR add-on does not load
You see: nothing in the headset, and Settings › System › Running in stays on WAITING FOR A VR GAME while the sim runs.
| Check | Fix |
|---|---|
| VR add-on reads NOT REGISTERED | Choose REGISTER. |
| You moved the app's folder | Start the app from the new folder, then REGISTER. |
| VR runtime reads NONE | Set your headset's OpenXR runtime as the active one (in Virtual Desktop, Meta Quest Link or SteamVR). |
| The sim runs on SteamVR only | Install OpenComposite for that sim (setup step 3). |
| The sim draws with DirectX 12 or Vulkan | Switch the sim to DirectX 11. Other renderers are not supported. |
| Other layers lists other add-ons | Turn them off one at a time to find a clash. |
A dashboard shows WAITING
You see: the card's badge stays on WAITING, and the panel in VR is empty.
| Check | Fix |
|---|---|
| SimHub is closed | Start SimHub. |
| SimHub's web server is off | Turn it on in SimHub's settings (port 8888). |
| Source is Window and the window is closed or minimised | Open the window and leave it open, or switch the source to SimHub. |
| The URL was typed by hand | Re-add it from FROM SIMHUB. |
| Lite mode | Only the first dashboard shows in the headset (chapter 3). |
The cockpit does not show
You see: the sim runs in VR, but no wheel, dashboards or passthrough.
| Check | Fix |
|---|---|
| Home shows … is running in VR, not … | Choose SWITCH GAME. |
| Home shows …'s game file was not found. | Choose LOCATE and pick the game's .exe. |
| The ALL tile is off | Open the VR menu and turn ALL on. |
| The feature's own tile is off | Turn on WHEEL, DASHBOARDS or PASSTHROUGH. |
| The trial has ended | The wheel, passthrough and extra dashboards wait for a key (chapter 3). |
| Things appear far away or behind you | Recentre (chapter 10). |
The wheel turns the wrong way or too far
| Check | Fix |
|---|---|
| Turns the opposite way | Turn on Invert steering. |
| Spins about the wrong axis | Change Spin axis, or Flip spin direction. |
| Turns too far or not far enough | Set Steering range to your wheel's lock (Automobilista 2 needs this). |
| Turns about the wrong point | Set the Pivot, then ALIGN IN VR again. |
Passthrough has coloured edges
You see: a pink or blue rim around passthrough windows.
The rim comes from video compression at the edge of the key colour. Every chroma-key app has it. To shrink it:
- In Virtual Desktop: Similarity 15 to 25 %, Smoothness up, Sharpening off.
- Raise the bitrate, or use HEVC 10-bit or AV1.
- In the app, raise the window's Edge feather and keep Settings › Passthrough › Edge on Soft.
Passthrough shows nothing at all? Check that Virtual Desktop's passthrough is on and its key colour matches Key colour exactly.
The hands do not show
| Check | Fix |
|---|---|
| Hand tracking is off on the headset | Turn it on in the headset's settings. |
| The controllers are in your hands | Put them down. |
| Show hands and arms is off | Turn it on in Settings › Arms, or the ARMS tile. |
| The runtime does not pass hand tracking | Use Virtual Desktop. |
Low frame rate
- Settings › Lighting › Shadows to Low or off.
- Lower dashboard Resolution.
- Use a lighter wheel model.
- Settings › System › GPU cost per frame shows what costs most.
Still stuck?
Write to the support address on the website. Add the app version (Settings › System › Version) and the log files from %APPDATA%\CockpitXR\logs (cockpitxr_app.log, and cockpitxr_layer.log from the sim).