# Troubleshooting

This guide helps you diagnose and resolve common issues when using CloudXR.js for WebXR streaming.

## Common Issues

### I got a blank page when opening the URL or it streams 2D only in browser

For HTTP Mode:

If you're using HTTP mode (`http://`), you need to configure the Chromium browser to allow WebXR usage from insecure origins:

- Open Meta Quest 3 Browser or desktop Google Chrome
- Navigate to `chrome://flags`
- Search for "insecure", and locate "Treat insecure origins as secure"
- Enable the flag
- Then in the text box below the flag, add your development web server
  - You must include the protocol (`http`) and the port (`:8080`)
  - `http://your-ip-address:8080`
- De-focus the text box by "clicking somewhere else"
- A "Relaunch" message should appear at the bottom of the window
- Click "Relaunch"
- Verify the flags are set as intended in `chrome://flags`

For HTTPS Mode:

If you're using HTTPS mode (`https://`), you need to trust the SSL certificates:

- Navigate to your web server URL in the browser: `https://your-ip-address:8080`
- Accept the certificate warning by clicking "Advanced" → "Proceed to [your-ip-address] (unsafe)"
- If using a WebSocket proxy, also trust its certificate by visiting: `https://your-proxy-ip:48322`

See the Client Setup Guide for detailed SSL certificate configuration.

### Handtracking is not responsive when I start the WebXR session

You could pause the session by clicking the MENU button and resume the WebXR session. If the behavior persists, we advise to restart your Meta headset to clear up caches.

### Connection Issues

You might see an error with an error code (shown in hexadecimal format like `0xC0F22202`). In most cases, they are because of the following reasons:

- Verify the server address and port are correct
- Check network connectivity between client and server
- Ensure the CloudXR runtime is running on the server
- Verify firewall rules allow traffic
- Ensure UDP ports are not blocked
- Check for high network latency or packet loss
- Verify stable network connection (check for Wi-Fi disconnections)
- Test network quality (ping, bandwidth, packet loss)
- Ensure WebRTC is not blocked by browser settings or extensions
- Review network topology (double NAT, symmetric NAT issues)
- Setup TURN relay server if direct connection fails
- Check server configuration and logs
- Restart the CloudXR runtime if necessary

For most issues, you can consult the Networking Setup Guide for detailed configuration instructions and the issue should resolve.

## ❓ Getting Help

If you're still experiencing issues:

1. Check the console for error messages
2. Test with different browsers
3. Verify server configuration and logs
4. Check network conditions and requirements
5. Review the Session API documentation

For additional support, please reach out to NVIDIA CloudXR team.