Troubleshooting#

To contact NVIDIA with questions and comments about NVIDIA CloudXR™ SDK, or to report a bug, go to the CloudXR Forum.

If you are reporting a bug, provide the following information:

  • Operating system (server and client)

  • GPU model and driver version

  • Client device used

  • Steps to reproduce the issue

  • Log files from both client and server

  • For performance or network issues, share any captured traces or diagnostics

Network Troubleshooting#

This section provides troubleshooting guidance for network and connectivity issues with CloudXR streaming.

Connection Issues#

Basic Connectivity Checks:

  1. Verify that the server IP address is correct and reachable from the client device.

  2. Check that required ports are open on both server and network firewalls.

  3. Ensure client devices are on the correct Wi-Fi band (5 GHz or 6 GHz).

  4. Verify that firewall permissions have been granted to the CloudXR application.

  5. Confirm that the CloudXR Runtime is running on the server.

Port Verification:

Use network tools to verify port connectivity:

  • Apple native clients: Test TCP port 48010.

  • Web clients: Test TCP port 49100.

Network Analyzer is a useful app for testing connectivity on iOS:

../_images/network-analyzer-info.jpeg

Information tab: General network connection info#
../_images/network-analyzer-lan.jpeg

LAN tab: Scan for local servers#
../_images/network-analyzer-ports.jpeg

Tools tab: Ping server and check port 48010#

Note

For iPad or Vision Pro apps to access servers on the local network, they must display a permissions prompt to the user. If the prompt is not shown or is accidentally dismissed, navigate to the app settings to grant the permission manually, or reinstall the app.

Performance Issues#

Packet Loss, Latency, and Jitter Testing:

Run tests from both the client device and the server. packetlosstest.com is a useful tool. Use the following settings:

../_images/packet-loss-settings.png

Recommended test settings#
../_images/packet-loss-clean.png

Good test results - mostly flat latency#

Interpreting Results:

  • Latency should be consistently low with minimal spikes.

  • Packet loss should be negligible.

  • High jitter indicates network instability.

  • If wired tests are good but wireless tests are bad, check the Wi-Fi configuration.

Bandwidth Testing:

  1. Test bandwidth from both wired and wireless connections

    • For cloud streaming: Use speedtest.net or speed.cloudflare.com

    • For local streaming: Use iPerf to test between server and client

    • Ensure downstream bandwidth meets minimum requirements (100 Mbps)

Wi-Fi Interference Checks:

Use Wi-Fi analysis tools like WiFi Explorer on macOS to identify channel conflicts:

WiFi Explorer showing channel interference

WiFi Explorer displaying channel usage and interference#

  • Check for other routers on the same channel.

  • Change your router’s channel or turn off interfering routers.

  • Consider using channels 44 or 149 to avoid Apple device channel hopping.

Periodic Latency Spikes#

If you experience regular, high, periodic network latency spikes, they may be caused by Apple’s Wireless Direct Link (AWDL) protocol causing channel hopping:

Periodic latency spikes from channel hopping

Example of periodic latency spikes caused by channel hopping#

To mitigate AWDL-related issues:

  • Configure the router to use channels 44 or 149 (used by AWDL).

  • Disable Bluetooth, AirPlay, and Handoff features on the client device.

  • Disable Location Services and other features that trigger AWDL.

Cloud Streaming Issues#

For streaming from cloud servers:

  • Ensure that you have a stable internet connection with at least 200 Mbps downstream and 20 Mbps upstream

  • Verify that the connection has IPv4 support. (CloudXR currently does not support IPv6.)

  • Test the connection from both wired and wireless devices to isolate local network issues.

Web Client Issues (CloudXR.js)#

Certificate Trust Issues:

When using HTTPS mode, browsers may show certificate warnings for self-signed certificates.

  • Visit the proxy URL directly in the browser and accept the certificate.

  • On Meta Quest 3, navigate to the HTTPS URL, click Advanced, then click Proceed to [site] (unsafe).

  • For production, use properly signed TLS certificates.

Pico 4 Ultra Not Connecting:

  • Pico 4 Ultra requires HTTPS mode. HTTP is not supported.

  • Ensure that WebSocket SSL proxy is configured and running.

  • Trust the SSL certificate on the device.

For web client-specific issues, refer to the documentation in WebSocket Proxy Setup and Client Setup Guide.

Log Files#

CloudXR components generate log files that are essential for debugging issues.

Server Logs (CloudXR Runtime)#

Windows:

Server logs are written to the subdirectory logs under the CloudXR installation, or to %LOCALAPPDATA%\NVIDIA\CloudXR\logs\.

Linux:

Server logs are typically written to the current working directory or the user’s home directory.

Log Contents:

  • Connection events and errors

  • Streaming statistics

  • Client connection information

  • Runtime initialization status

Client Logs#

CloudXR Framework (Apple):

Logs are written to the Xcode console during development. For deployed applications, you can access logs through the system Console app or Xcode device logs.

CloudXR.js (Web):

Open the browser’s developer console (F12 or Cmd+Option+I) to view logs. CloudXR.js logs connection events, errors, and streaming statistics to the console.

Getting Support#

If you encounter issues not covered in this documentation:

  1. Check the forum: The CloudXR Forum contains solutions to common problems and community support.

  2. Gather information: Collect log files, network diagnostics, and steps to reproduce before reporting issues.

  3. Submit a bug report: Provide detailed information, including:

    • Server OS, GPU, and driver version

    • Client device and OS version

    • SDK versions used

    • Network configuration

    • Complete log files

    • Steps to reproduce

On this page