From db1170e63af5d15ce59f76d7f8e5b763bd22e7be Mon Sep 17 00:00:00 2001
From: Jeffery Tse <jeff.tse@nyu.edu>
Date: Tue, 7 Jul 2026 01:02:55 -0400
Subject: [PATCH] fix(docker): detect snap+WSL2 GPU passthrough
 incompatibility, document fix

---
 docs/setup.md               | 15 +++++++++++++
 scripts/check-docker-gpu.sh | 42 +++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/docs/setup.md b/docs/setup.md
index fd63e02a5..7f81556f8 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -151,6 +151,21 @@ scripts/check-docker-gpu.sh --enable-nvidia-overlay
 scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
 ```
 
+> **WSL2 + snap Docker.** If `docker run --gpus all ...` fails with
+> `failed to fulfil mount request: open /usr/lib/wsl/lib/libdxcore.so: no
+> such file or directory`, check whether Docker was installed via `snap`
+> (`snap list docker`, or `docker info --format '{{.DockerRootDir}}'` reports
+> a path under `/var/snap/docker/`). Snap's confinement prevents Docker from
+> seeing the GPU library WSL2 injects at `/usr/lib/wsl/lib`, even though the
+> file exists on the host — installing or reconfiguring
+> `nvidia-container-toolkit` will not fix this, since the toolkit isn't the
+> problem. `scripts/check-docker-gpu.sh` detects this combination and calls
+> it out directly. The fix is to remove snap Docker and install the official
+> apt-based Docker Engine instead
+> ([docs.docker.com/engine/install](https://docs.docker.com/engine/install/)),
+> then re-run `nvidia-ctk runtime configure --runtime=docker` and restart
+> Docker.
+
 Safety notes:
 - The app never installs host GPU runtime automatically.
 - The app never edits `.env` automatically.
diff --git a/scripts/check-docker-gpu.sh b/scripts/check-docker-gpu.sh
index b80122ee2..d30d4c5f9 100755
--- a/scripts/check-docker-gpu.sh
+++ b/scripts/check-docker-gpu.sh
@@ -215,6 +215,28 @@ _check_nvidia_smi() {
 }
 
 # Returns 1 if Docker is unavailable (callers should stop further GPU checks).
+# WSL2 only: Docker installed via snap confines the container runtime's mount
+# namespace, so it cannot see the GPU library WSL2 injects at
+# /usr/lib/wsl/lib/libdxcore.so even though the file exists on the host.
+# Symptom: `docker run --gpus all ...` fails with
+# "failed to fulfil mount request: open /usr/lib/wsl/lib/libdxcore.so: no
+# such file or directory". No nvidia-container-toolkit install or
+# `nvidia-ctk runtime configure` fixes this — the fix is to stop using the
+# snap package. DockerRootDir is the reliable way to tell: snap installs
+# report a path under /var/snap/docker/ instead of the normal /var/lib/docker.
+_is_wsl() {
+    grep -qi microsoft /proc/version 2>/dev/null && return 0
+    [ -d /usr/lib/wsl ] && return 0
+    return 1
+}
+
+_is_docker_snap() {
+    case "$(docker info --format '{{.DockerRootDir}}' 2>/dev/null)" in
+        */snap/docker/*|*/snap.docker/*) return 0 ;;
+    esac
+    return 1
+}
+
 _check_docker() {
     _info "Checking Docker..."
     if ! command -v docker >/dev/null 2>&1; then
@@ -258,6 +280,26 @@ _check_gpu_passthrough() {
         echo
         _fail "GPU passthrough failed. Check these steps in order:"
         echo
+        if _is_wsl && _is_docker_snap; then
+            _warn "Detected: Docker installed via snap, running on WSL2."
+            _warn "This is a known incompatibility, not a toolkit/config problem:"
+            _warn "  snap confines Docker's mount namespace, so it cannot see the"
+            _warn "  WSL2-injected GPU library at /usr/lib/wsl/lib/libdxcore.so even"
+            _warn "  though the file exists on the host. Installing/reconfiguring"
+            _warn "  nvidia-container-toolkit will NOT fix this — the numbered"
+            _warn "  steps below will not help until Docker itself is replaced."
+            echo
+            _info "Fix: remove snap Docker and install the official apt-based Docker"
+            _info "Engine instead (unsandboxed, can see /usr/lib/wsl/lib):"
+            echo
+            echo "  sudo snap remove docker"
+            echo "  # then follow: https://docs.docker.com/engine/install/ubuntu/"
+            echo "  sudo nvidia-ctk runtime configure --runtime=docker"
+            echo "  sudo systemctl restart docker"
+            echo
+            _info "Re-run this script afterward to confirm passthrough works."
+            echo
+        fi
         echo "  1. Install NVIDIA Container Toolkit (if not already installed):"
         echo "     Arch:    sudo pacman -S nvidia-container-toolkit"
         echo "     Debian:  sudo apt install nvidia-container-toolkit"