VR Deck

Troubleshooting

A key with a badge is telling you the one thing that is missing. Most of what follows is that badge, what it means, and the step that clears it.

1. Badges on keys
2. The overlay
3. Ports and feeds
4. Keys
5. The companion and the logs

Badges on keys

NO PORT on a MIDI key

Why: the companion is connected but does not list the MIDI output the key names. A press only alerts; nothing is sent.

Fix: create the loopMIDI port with the exact name the key uses (loopMIDI Port for the shipped Mover keys). On Windows 11 (build 26100 and later) a port created while the Windows MIDI Service runs stays invisible until the service restarts: in an administrator PowerShell run Restart-Service midisrv -Force, or restart the PC. Then restart the Stream Deck app (quit it from its tray icon; closing the window only hides it). The key undims by itself once the port is listed; the list is re-checked every 15 seconds. Details on the Mover page.

NO VR on a VR Recenter or VR Look key

Why: the companion is not connected to the plugin. These keys need the companion for everything they do, so a press only alerts.

Fix: give it a few seconds after the Stream Deck app starts; the plugin starts the companion by itself. If the badge stays, quit the Stream Deck app from its tray icon and start it again, and look at %LOCALAPPDATA%\VRDeck\companion.log for the reason. A missing .NET 10 Desktop Runtime is one the Setup key reports. The other keys do not need the companion for their badges: a VR Calibrate key shows the companion and SteamVR status in words.

OUTPUTS 1ST on the Sources on key

Why: the key carries the Mover gate and no Mover feed packet arrived in the last 2 seconds, which means the outputs that feed the plugin are not up. A press only alerts; nothing is sent.

Fix: start Outputs first; that connects Mover's UDP output, the feed comes, and the key redraws within a few seconds. If you never set the feed up, set up Mover's UDP output, or switch the key's Mover gate to None in its inspector; with no feed the gated key never fires.

VST OFF on the Passthru key

Why: Pimax Play's VST (lab) switch is off, so passthrough would not toggle. Pimax drops that switch on headset reconnects and app relaunches. The key still sends its shortcut when pressed (harmless), with an alert.

Fix: turn VST (lab) on in Pimax Play. The key returns to normal by itself. VR Deck cannot do this for you: Pimax has no shortcut for the switch, and VR Deck never writes other programs' files. See the Pimax page.

MK.2 on a page key

Why: the Nudge, Mover, DiRT, Look and Home page keys page inside the shipped profiles, which are made for the 15-key Stream Deck MK.2 and original. On any other deck such a key is dimmed and alerts when pressed.

Fix: on other decks lay the keys out yourself: single-adjustment VR Nudge keys, the gauges and tiles you want, on your own pages.

no data on a Game data tile or a gauge

Why: no packet for two seconds. DiRT Rally 2.0 sends packets only while a stage runs: menus, the pause screen and the results screen send nothing. Mover sends only while its UDP output is connected.

Fix, game: drive a stage. If the tiles stay dark, check the <udp> line in both settings files and its port; the Setup key's Game telemetry row names what is wrong. See the DiRT page. Fix, Mover: start the outputs; make sure the UDP module is Binary BE on port 8788 with one tag per actuator in its send string, and that the Mover file was saved after the module was added. See the Mover page.

The overlay

Nothing shows in the headset

• Is SteamVR running? The companion waits for it and never starts it. The VR Calibrate key says so while SteamVR is off.
• Is the game on another OpenXR runtime? PimaxXR, Oculus and VDXR have no overlay API, so there is no overlay there. Run the game through SteamVR.
• Is the overlay switched off? The VR Deck on/off key (VR Show/Hide) reads ON or OFF, or says why there is nothing to show: SteamVR off, Not calibrated.
• Is this deck calibrated? Each deck has its own entry; a new deck shows not calibrated until its three touches.
• Is a deck connected? With no deck connected the companion hides the overlay until one is back.
• Opacity turned down? The Look page's Opacity keys go down to 20 %; each key shows the current value.

The grid is not on the deck

• A small offset: the Nudge page (page 2). Every press is saved at once.
• Inside-out headset after a cold start: the tracking space may have come back shifted, and the stored pose is off by that shift. Nudge it back or recalibrate; if it happens at every cold start, try the standing tracking space as described on the calibration page.
• Switched between base-station and inside-out tracking: a different space. Calibrate once per tracking mode.
• A second deck of the same type: it borrows the first deck's calibration until it has its own; the first nudge on it makes its own copy, or calibrate it with three touches.
• The grid is the wrong size: the size comes from the deck model, verified for the MK.2 only. Use the Size + and − keys on the Nudge page; the Mini, XL, +, Neo and the Galleon keyboard use published sizes and may need it.

The overlay turned or moved after a recenter

Normally it does not: within a session every recenter is compensated and the headset shows Recenter detected or Recentred: deck overlay kept in place. If a Pimax reset in SteamVR comes out turned relative to Pimax's own home, SteamVR's room setup was done facing another way than the desk: redo room setup from the desk, or take the headset off and put it on again. If the grid moved anyway, a nudge or a fresh calibration puts it back; companion.log says what the detector saw (recenter detected, or head jump ... ignored with the reason).

Text between the keys is hard to read while the scene moves

The key tiles are solid, but the gaps between them were see-through by design. The backplate is the fix: a dark plate under the whole deck footprint. On the Look page (page 5), press Plate to switch it on and Plate + to darken it; each key shows the current value. Both settings persist.

Ports and feeds

"Port 20777 is in use by another program"

Why: DiRT Rally 2.0 sends its telemetry packet to one address, so only one program receives it. Another dashboard (SimHub, a phone dashboard) already holds the port, and the plugin leaves it alone rather than taking the dashboard's feed. The Game data inspector's feed line and the Setup row say so, and the plugin tries again every 5 seconds while a Game data key is on the deck.

Fix: either let the dashboard forward the packet to the plugin's port if it can, or give the plugin a different gameFeedPort in settings.json and accept that the plugin then sees nothing (the game still sends to the port in its <udp> line). A dashboard started after a Game data key is already listening gets nothing, so start the dashboard first. Details on the DiRT page.

Mover moves the rig flat but not in VR

Mover's patcher switches the game's <custom_udp> line on in the flat-screen settings file only. The VR file needs the same line: the Setup key's Game telemetry row shows the exact line and the VR file to paste it into, with the game closed. VR Deck's own <udp> line for the DiRT page is separate; both can be on. See Game telemetry into Mover, in VR.

The gauges never move

• Mover's UDP output must be started, and the Mover file saved after the module was added; otherwise it is back to its defaults at the next start.
• Type Binary BE, port 8788, one <R0.An.B> tag per actuator in the send string, CRC none.
• If Mover's UDP module has no IP field it broadcasts: set "moverFeedBind": "0.0.0.0" in settings.json and allow the Stream Deck app through the Windows firewall when asked.
• The gauge inspector's live line tells you what arrives: Mover is sending 6 actuators (via udp, last packet 120 ms ago).

Keys

A Mover key does nothing inside a game

In a running stage the game holds the keyboard exclusively, so no keystroke reaches Mover; keyboard-edition keys work from Mover's menus and the desktop only. That is by design, and the MIDI edition is the answer: its notes reach Mover inside a stage, after the one-time binding on Mover's Options page. A MIDI key that does nothing shows NO PORT (above) or is not bound yet: bind it.

One deck key fires two things in Mover

A note held by two fields on Mover's Options page fires both. One control per field: clear the earlier test binding, so each note is bound to exactly one field.

A Toggle shows the wrong state

The Toggle flips its state once its shortcut was sent, whether or not the other program received it. Inside a game that holds the keyboard the deck can say one thing and Mover another. Use the MIDI edition for Mover; its notes get through. A Toggle is never an emergency stop.

Other plugins' keys look static or blank in the headset

Other plugins' keys show in the headset as static tiles (name and stored picture), not their live content: plugins cannot see each other's pictures. A key whose picture changes while it runs (a clock, a meter, a mute state) keeps its stored picture in VR; a key you just added may show only its name and a glyph until the app has stored a picture for it. Tip: give such a key an icon from the Stream Deck app's icon library, or your own file, and the overlay shows that icon. Dials and touch strips are not mirrored. To switch the mirror off, set "mirrorOtherKeys": false in settings.json.

The Setup key is amber

It counts the steps left among the checks you have ticked. Open its inspector: each row names the one step left. Untick the checks that do not apply to your PC (no rig: Mover, loopMIDI, Game telemetry; no Pimax headset: Pimax Play) and the key goes green on the companion and SteamVR alone.

The companion and the logs

Windows asks about VRDeck.Companion.exe

The companion is the small Windows program inside the package that draws the overlay and sends the keystrokes and MIDI. The plugin starts it, it talks to the plugin on 127.0.0.1 only, and it connects nowhere else. If Windows SmartScreen or an antivirus asks about it, it is this companion.

Where the logs are

• %LOCALAPPDATA%\VRDeck\companion.log: the companion. Which decks it sees (deck devices:), which calibration it loaded, what SteamVR said, every recenter it detected or ignored.
• %APPDATA%\Elgato\StreamDeck\Plugins\com.vrdeck.keys.sdPlugin\logs\: the plugin. One line for every press that could not do its job and why.

When you write for help, include the lines from both logs around the time of the problem, your deck model, your headset and whether it tracks with base stations or inside-out, and the Stream Deck app version. Contact details are on the about page.