Troubleshooting the OpenXR module
Nothing is ever received
Cause. The HEAT OpenXR API layer is not installed, or is not registered with the OpenXR loader, so nothing is ever listening on the other end of the named pipe.
Fix. Confirm the layer is installed and enabled - with SteamVR, under Settings → OpenXR → Manage OpenXR Layers - and that the VR application using it is running. See Overview.
The connection repeatedly connects then disconnects
Cause. The log shows HEAT OpenXR data pipe connected, publishing at native rate followed
soon after by HEAT OpenXR data pipe disconnected, reconnecting. The layer process is
starting, then exiting or being restarted - often because the VR application itself is
restarting, not because of this module.
Fix. This module retries the connection automatically every second, indefinitely; no action is needed on the module side. Investigate why the layer or the VR application is restarting.
One eye’s video is intermittently missing
Cause. The layer pairs both eyes’ H264 output for the same tick before sending, but only waits a bounded amount of time for a straggler eye - see Data produced. A tick where one eye’s encoder pipeline ran slightly behind sends with only the healthy eye’s video. This is expected layer behavior, not a defect in this module.
Fix. If it happens consistently rather than occasionally, investigate the layer’s own encoder health (GPU load, dropped frames) rather than this module’s settings - there is nothing in this module to adjust for it.
Log shows repeated “Failed to parse SimulationFrame from OpenXR layer payload”
Cause. The bytes read off the pipe did not parse as a SimulationFrame. This module and the
HEAT OpenXR API layer have no protocol version negotiation and no backward compatibility between
versions - they are only guaranteed to work together deployed in lockstep. A mismatched pair
(module and layer built against different SimulationFrame schema versions) produces exactly
this symptom.
Fix. Confirm the installed HEAT OpenXR API layer version matches what this module version expects. There is no fallback - a parse failure drops that tick’s data and moves on to the next line on the pipe.