> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

> Troubleshoot NVIDIA AI Workbench full local installations and WSL

# Troubleshoot AI Workbench on Windows Systems

## Overview

**Most Windows troubleshooting issues are related to the WSL 2 dependency used by the full local install.**

The Desktop App in remote-only mode has fewer system dependencies and is less likely to encounter Windows-specific setup issues.

The full local install depends on WSL 2. In some cases, WSL 2 can fail during install, after Windows resumes from sleep, or when AI Workbench opens a local location window.

**Full local install failures usually happen while AI Workbench imports and configures the WSL distribution.**

When Windows install errors occur, they most often happen while AI Workbench imports and configures the `NVIDIA-Workbench` distribution.

**Location window failures can also be related to the local WSL environment.**

If AI Workbench cannot open a local location window after a successful full local install, restarting Windows or shutting down WSL 2 usually resolves the issue.

## Recover from WSL 2 Issues

**If the full local install fails or a local location window does not open, restart Windows and WSL 2.**

1. Close AI Workbench.

2. Restart your computer.

3. Open a Windows terminal.

4. Shut down WSL 2:

   ```powershell
   wsl --shutdown
   ```

5. Open AI Workbench again.

6. Retry the full local install or open the local location again.

**If the issue continues, create an error report.**

For more information, see [Logs, Runtime Files and Error Reports](/ai-workbench/reference/troubleshooting/logging).

## Troubleshoot NVIDIA Sync mDNS Connections

**NVIDIA Sync can discover and connect to a remote device on Windows while AI Workbench is unable to open the Sync-managed location.**

This can happen when Sync discovers the device through multicast DNS (mDNS) but AI Workbench connects from the `NVIDIA-Workbench` WSL 2 distribution.
The default WSL 2 NAT network does not provide the same multicast network path that is available to applications running directly on Windows.

**Use mirrored networking to make the Windows network interfaces and multicast traffic available to WSL 2.**

AI Workbench supports mirrored networking but does not enable it for you.
For the complete setup procedure and system requirements, see [Use Mirrored Networking](/ai-workbench/reference/windows-full-local-reference#use-mirrored-networking).

{/*
Internal documentation note: Mirrored networking provides the multicast network path, but the
NVIDIA-Workbench distribution did not include libnss-mdns when checked on 2026-07-16. Confirm
whether Sync passes a resolved IP address, another resolver handles the mDNS hostname, or the
distribution must add mDNS name-resolution support. Do not document libnss-mdns installation
as a supported user requirement until this behavior is resolved with engineering.
*/}

**If the Sync-managed remote location does not open after you enable mirrored networking, confirm the WSL 2 configuration and restart WSL 2.**

1. Close AI Workbench.

2. Open `%UserProfile%\.wslconfig` in a text editor.

3. Confirm that the file contains the following configuration:

   ```ini
   [wsl2]
   networkingMode=mirrored
   ```

4. Save the file if you changed it.

5. Open PowerShell.

6. Shut down WSL 2:

   ```powershell
   wsl --shutdown
   ```

7. Open NVIDIA Sync.

8. Launch AI Workbench for the remote device from NVIDIA Sync again.

**Success: AI Workbench opens the Sync-managed remote location.**

### Return to NAT Networking

**Remove the mirrored-networking setting if you need to return WSL 2 to NAT networking.**

1. Close AI Workbench.
2. Open `%UserProfile%\.wslconfig` in a text editor.
3. Remove the `networkingMode` line, or set it to `networkingMode=nat`.
4. Save the file.
5. Open PowerShell and run `wsl --shutdown`.
6. Open AI Workbench.

## Related Topics

- [Use NVIDIA Sync with AI Workbench](/ai-workbench/how-to/locations/use-nvidia-sync)
- [Windows Full Local Install Reference](/ai-workbench/reference/windows-full-local-reference)
- [AI Workbench Support Matrix](/ai-workbench/reference/support-matrix)
- [Troubleshooting and Logging](/ai-workbench/reference/troubleshooting/logging)