Omniverse Spatial Troubleshooting: CloudXR Connection, Build, and Streaming Issues#

Note

Applies to: Spatial Extensions, Kit 109.0.3+, CloudXR 6

This troubleshooting reference covers common issues across the Kit XR server, Apple clients, and Meta/web clients. Start with the section that matches where the problem occurs.

Server Issues#

Kit Application Fails to Build#

Symptom

Solution

Build errors after adding XR extensions

Verify you are on the 109.0.3 branch of kit-app-template

Missing dependencies

Run a clean build: ./repo.sh build -x (Linux) or .\repo.bat build -x (Windows)

Template creation fails

Ensure you accepted the Omniverse Licensing Terms on first run

Long path errors (Windows)

Enable long path support or move workspace to a shallow directory

Kit Application Fails to Launch#

Symptom

Solution

Shader compilation takes very long

Normal on first launch (5-8 minutes). Subsequent launches are faster

Application crashes on startup

Check the Kit log for errors (see Log Locations below)

XR panel not visible

Open from Window menu, then dock it

Extensions fail to load

Verify extension paths in your .kit file (folders.'++' = [...])

GPU driver in blocklisted range

Drivers in the range 575.00 – 576.52 are blocklisted by the Omniverse runtime. Update to 581.42 or later.

XR Does Not Start#

Symptom

Solution

“Start XR” button does nothing

Check that XR extensions are in [dependencies] and the build includes them

“Status: Waiting on Connection” does not appear

Verify the OpenXR Runtime selection matches your target client

“OpenXR runtime not found”

Select CloudXR 6 (Native) or CloudXR 6 (WebRTC) instead of System

Viewport is black after starting XR

Ensure a USD scene is loaded before starting XR

2D Streaming Extensions Conflict#

The 2D streaming extensions (omni.kit.livestream.webrtc, omni.kit.livestream.app) initialize a separate 2D streaming pipeline that conflicts with the CloudXR XR stereo pipeline. They cannot coexist in the same Kit application.

Symptom

Solution

XR extensions fail to load

Remove omni.kit.livestream.webrtc and omni.kit.livestream.app from your .kit file. These initialize a 2D streaming pipeline that conflicts with the XR stereo pipeline

Viewport shows flat 2D stream

You might have a streaming .kit file selected instead of your XR .kit file

Apple Client Issues#

Build and Signing#

Symptom

Solution

Code signing error

Verify Apple Developer Program membership is active. Check provisioning profiles in Xcode

Missing entitlement

Low-Latency Streaming requires ADP membership. To build without it, clear Code Signing Entitlements in Build Settings

CloudXR Framework not found

Re-add the package dependency: https://github.com/NVIDIA/cloudxr-framework

Build fails on simulator

CloudXR streaming does not work in the simulator. Build for a physical device or use simulator for UI testing only

Bundle ID conflict

Change the bundle identifier in Config.xcconfig or project settings to a unique value

Connection#

Symptom

Solution

Cannot connect to server

Verify server IP, ensure CloudXR 6 (Native) is selected in Kit, check firewall ports

Connection drops immediately

Check WiFi signal strength, verify same subnet, ensure XR is still running in Kit

“Failed connection attempt” error

Confirm the server IP is correct and the device is on the same network

DNS resolution failure

Use the server’s IP address directly instead of a hostname

Timeout / no response

Check firewall for ports 47995-48012 (TCP/UDP)

Streaming Quality#

Symptom

Solution

Low resolution or blurry

Increase resolution preset in the app settings

Stuttering / frame drops

Check WiFi bandwidth (need 200+ Mbps), reduce render quality in Kit

High latency

Ensure server is wired to router, use 5 GHz WiFi band, reduce network hops

No audio

Audio streaming requires a Windows server

Web Client Issues#

Build and Hosting#

Symptom

Solution

npm install fails

Verify Node.js v20+ is installed. Check the path to the CloudXR SDK tarball

npm run build fails

Clear node_modules and reinstall: rm -rf node_modules && npm install

Web server not accessible from headset

Check firewall for port 8080, verify server and headset are on same network

Connection#

Symptom

Solution

CONNECT button stays green (no streaming)

Check browser console for errors. Verify Kit is running with CloudXR 6 (WebRTC) and port 49100 is open

Mixed content error

You are loading the page through HTTPS but connecting using ws://. Set up a WebSocket proxy (refer to Networking Guide)

WebXR not available

On Quest 3 HTTP mode: enable WebXR Incubations in chrome://flags

No XR button in browser

IWER might not have loaded. Check that no conflicting Chrome extensions (Immersive Web Emulator) are installed

Pico cannot connect

HTTPS mode is required for Pico 4 Ultra. HTTP is not supported

Certificate error on device

Navigate to the certificate URL and accept it, or use properly signed certificates

Streaming Quality#

Symptom

Solution

Low FPS on Quest 3

Reduce framebuffer scale to 1.4, enable foveation (MEDIUM), cap frame rate at 90 Hz

High latency

Ensure server is wired, use 5 GHz WiFi, check with iperf3 for bandwidth

Visual artifacts

Reduce streaming bitrate, check GPU utilization on server

Audio not working

Audio streaming availability depends on the server platform and runtime

Network Issues#

Symptom

Solution

Connection refused

Wrong port number. Apple: ports 47995-48012. Meta: port 49100 (or 48322 for WSS proxy)

Connection timeout

Firewall blocking traffic. Open required ports (see Networking Guide)

Intermittent disconnects

WiFi instability. Check signal strength, switch to less congested channel, ensure 5 GHz

Very high latency (> 40 ms)

Too many network hops. Wire the server directly to the WiFi router

Client isolation

Router is blocking client-to-server traffic. Disable AP/client isolation in router settings

Log Locations#

Kit Server Logs#

Windows:

%USERPROFILE%\.nvidia-omniverse\logs\Kit\<app-name>\

Linux:

~/.nvidia-omniverse/logs/Kit/<app-name>/

Kit logs contain extension loading, XR system status, and CloudXR runtime messages.

CloudXR Runtime Logs#

CloudXR runtime logs are included in the Kit log output. Search for CloudXR or cxr in the logs.

Apple Client Logs#

  • Xcode console: View real-time logs when the device is connected

  • Vision Pro device logs: Use Console.app on macOS, filter by CloudXRViewer

  • iPad device logs: Use Console.app on macOS, filter by CloudXRViewer

Web Client Logs#

  • Browser developer console: Press F12 in Chrome, go to the Console tab

  • Quest 3 remote debugging: Connect Quest 3 using USB, open chrome://inspect in desktop Chrome

  • Pico remote debugging: Similar to Quest: connect using USB and use Chrome DevTools

Diagnostic Checklist#

When something is not working, run through this checklist:

  • Kit server running?: Application is open with a scene loaded

  • XR started?: Viewport shows “Status: Waiting on Connection”

  • Correct runtime?: CloudXR 6 (Native) for Apple, CloudXR 6 (WebRTC) for Meta/web

  • Same network?: Server and client on the same subnet

  • Server reachable?: Ping the server from the client network

  • Ports open?: Firewall allows CloudXR ports

  • WiFi quality?: 5 GHz band, > 200 Mbps, < 20 ms latency

  • Client configured?: Correct server IP, correct port, correct mode (AR)

  • No conflicting extensions?: No 2D streaming extensions in the .kit file

  • Check logs: Server logs, client logs, browser console

Getting Help#

Documentation:

Community and Support: