Troubleshooting#

This troubleshooting reference covers common CloudXR.js issues and first-pass diagnostics.

Common Symptoms and Fixes#

WebXR not available or no immersive session#

  • For HTTP testing on Quest, configure insecure-origin browser flags for your dev URL.

  • For HTTPS deployments, trust both web app and proxy certificates.

  • Confirm the exact URL, port, and protocol expected by your hosting mode.

Connection fails before stream starts#

  • Verify signaling endpoint, protocol (ws:// vs wss://), and port.

  • Confirm firewall/NAT rules for required TCP and UDP ports.

  • If using a proxy, validate target routing and certificate trust.

Media connects but stream is unstable#

  • Check latency, jitter, and packet loss against Network Setup.

  • Reduce bitrate and/or stream resolution for constrained networks.

  • Verify that server GPU and encoder capacity are not saturated.

Hand Tracking Not Responsive#

  • Pause and resume immersive mode.

  • Restart the headset if behavior persists.

  • Confirm runtime and client are both actively streaming.

Connection Issues and Error Categories#

Signaling Errors (WebSocket)#

Typical indicators include connection refusal/timeouts and signaling-stage failures.

Quick checks:

  • Verify server/proxy address and signaling port.

  • Ensure TCP signaling port is reachable.

  • Confirm firewall allows signaling traffic.

Media Connection Errors (WebRTC/UDP)#

Typical indicators include successful signaling but no media stream.

Quick checks:

  • Verify UDP media port forwarding and firewall rules.

  • Verify NAT endpoint/port configuration.

  • Configure STUN/TURN for restrictive networks.

Other Streaming Errors#

  • Check network quality and available bandwidth.

  • Confirm CloudXR Runtime is active and using the expected profile.

  • Review runtime logs for stream start/stop failures.

Working with Error Codes#

CloudXR.js reports technical error codes with stream failures. Capture the code and include it in bug reports.

onStreamStopped: (error?: CloudXR.StreamingError) => {
  if (error?.code) {
    const hexCode = '0x' + error.code.toString(16).toUpperCase();
    console.error(`${error.message} (${hexCode})`);
  }
}

NAT Debug Checklist#

  1. Validate external TCP signaling reachability.

  2. Validate external UDP media reachability.

  3. Confirm runtime is configured with public endpoint and external ports.

  4. If using mediaAddress in the client, confirm runtime was started with NV_CXR_STREAMSDK_ENABLE_ICE=0.

  5. Confirm client uses public endpoint values, not private LAN values.

  6. You can also consider STUN/TURN if direct NAT mapping is insufficient for your use case.

NAT Debugging Steps#

  1. Verify signaling port accessibility (TCP):

    nc -zv <public-ip> <signaling-port>

  2. Verify media port accessibility (UDP):

    nc -zv <public-ip> <media-port>

  3. Bidirectional UDP test:

    On the server:

    nc -u -l <internal-media-port>

    On the client:

    echo "test" | nc -u <public-ip> <external-media-port>

Network Performance Checks#

Bandwidth:

iperf3 -s
iperf3 -c <server-ip>

Latency:

ping <server-ip>

If latency, jitter, or packet loss exceed guidance, reduce streaming load and improve Wi-Fi/network quality before further debugging.