Is this page helpful?

Troubleshooting#

This section addresses common issues you may encounter when setting up, building, or running DSX applications.

Prerequisites Validation#

Before troubleshooting, verify your prerequisites are correctly installed:

Verify GPU and Driver:

# Linux
nvidia-smi

# Expected output should show:
# - Driver Version: 570.169 or higher
# - CUDA Version: 12.x
# - GPU Name: RTX Pro 6000 Blackwell or better

Verify Node.js and npm:

node --version  # Should be v20.x or higher
npm --version   # Should be 9.x or higher

Verify Build Tools:

gcc --version
g++ --version

Open Visual Studio Installer and verify “Desktop development with C++” workload is installed.

Build and Compilation Issues#

Build fails with “missing dependencies” or “package not found”#

Symptoms:

  • Error messages about missing packages or libraries

  • Build script exits with non-zero code

Solutions:

  1. Install build essentials:

sudo apt-get update
sudo apt-get install build-essential

  1. Clean and rebuild:

./repo.sh clean
./repo.sh build

  1. Verify Visual Studio workload:

  • Open Visual Studio Installer

  • Ensure “Desktop development with C++” workload is installed

  • Install Windows SDK if missing

  • Follow the Windows Developer Configuration instructions

  1. Clean and rebuild:

.\repo.bat clean
.\repo.bat build

Build takes extremely long time (>30 minutes)#

Symptoms:

  • Build process hangs or is very slow

  • High CPU usage but no progress

Solutions:

  1. Check available disk space:

    df -h
# Ensure at least 20GB free space

    Get-PSDrive C
# Ensure at least 20GB free space

  2. Check system resources:

    • Ensure sufficient RAM (64GB+ recommended)

    • Close other resource-intensive applications

  3. First build is expected to be slow (15-20 minutes) - subsequent builds are faster (2-3 minutes)

Linux System Configuration Issues#

Application hangs during renderer initialization (IOMMU / zenity dialog)#

Symptoms:

  • The Kit application appears to hang for 30+ minutes during startup

  • No error messages in the terminal – the process is silently waiting

  • If you have physical access to the display, a zenity warning dialog about IOMMU is visible

  • This typically occurs on headless or remotely accessed Linux machines

Cause:

IOMMU (Input-Output Memory Management Unit) is enabled on the system. The GPU foundation plugin detects this and displays a zenity dialog that requires manual dismissal. On headless or remote systems, nobody can click “OK” to dismiss it, so the application blocks indefinitely.

Solution:

Disable IOMMU at the system level. This is a machine configuration change, not a software fix. The typical approach is one or both of:

  • BIOS/UEFI: Disable IOMMU in your system’s BIOS settings. The option may be labeled “IOMMU”, “AMD-Vi”, or “Intel VT-d” depending on the platform. Consult your hardware manufacturer’s documentation.

  • Kernel parameter: Add iommu=off to your kernel boot parameters (for example, in /etc/default/grub on the GRUB_CMDLINE_LINUX_DEFAULT line), then run sudo update-grub and reboot.

After rebooting, verify IOMMU is disabled:

dmesg | grep -i iommu

Streaming and WebRTC Issues#

NVST Error: NVST_R_BUSY in terminal output#

Symptoms:

  • Error message appears in terminal when stopping the Kit streaming application:

    2026-02-23T16:45:45Z [651,338ms] [Error] [omni.kit.livestream.webrtc.plugin] NVST Error: NVST_R_BUSY

Solution:

Note

This error can be safely ignored. These errors are emitted when the user stops the Kit streaming application and will be addressed in a future release.

Web Frontend Display Issues#

“Unable to display map. WebGL2 support is required”#

Symptoms:

  • The ArcGIS 3D globe does not render

  • The message “Unable to display map. WebGL2 support is required” appears where the globe should be

  • The rest of the web frontend may load normally

Solution:

Your browser’s hardware acceleration is disabled. The ArcGIS globe requires WebGL2, which depends on GPU-backed rendering in the browser.

  1. Enable hardware acceleration in your browser:

    • Chrome: chrome://settings/system > enable Use graphics acceleration when available

    • Edge: edge://settings/system > enable Use graphics acceleration when available

    • Firefox: about:preferences > Performance > uncheck Use recommended performance settings > enable Use hardware acceleration when available

  2. Relaunch the browser when prompted.

  3. Verify WebGL2 is active by navigating to chrome://gpu and confirming WebGL2 shows as Hardware accelerated.

Note

This is a client-side browser setting. If you are accessing the frontend remotely (for example, port-forwarding from a Linux server to a Mac), the fix applies to the browser on your local machine, not the remote server.

Getting Additional Help#

If you continue to experience issues:

  1. Check logs:

    • Kit application logs: Check terminal output where you ran ./run_streaming.sh (Linux) or .\run_streaming.bat (Windows)

    • Web frontend logs: Check browser Developer Tools Console

    • System logs:

    journalctl -xe

    Open Event Viewer (eventvwr.msc) and review Application and System logs.

  2. Verify your setup matches prerequisites:

    • Review Prerequisites section

    • Ensure all required software is installed and up to date

  3. Search for similar issues: