Request: Document kernel compatibility requirements and support WSL2 kernel 6.18+

[valorisa]

Summary

Docker Desktop 4.73.0 silently fails to start when WSL2 uses a custom kernel compiled from Microsoft's official linux-msft-wsl-6.18.y branch. The failure is completely silent — the UI shows an infinite spinner, docker info returns HTTP 500, and nothing in the logs hints at a kernel problem.

Request: Please provide documentation on kernel compatibility requirements and consider supporting kernel 6.18+.

Environment

Component	Version
Docker Desktop	4.73.0 (build 226246)
Docker Engine	29.4.3
Docker API	v1.54
Windows	11 Enterprise 10.0.26200
WSL	2.7.3.0
Default kernel	6.6.114.1-microsoft-standard-WSL2 (works)
Custom kernel	6.18.20.3-microsoft-standard-WSL2+ (breaks Docker)

Problem

When .wslconfig specifies a custom kernel (6.18.y), Docker Desktop's bootstrap process fails at two levels:

1. ISO9660 mount failure

wsl-bootstrap cannot mount docker-desktop.iso and docker-wsl-cli.iso because the kernel has CONFIG_ISO9660_FS=m (module), and WSL2 never provides /lib/modules/. The mount fails silently:

mount: unknown filesystem type 'iso9660'

This is fixable by recompiling with CONFIG_ISO9660_FS=y.

2. LinuxKit initd netlink ABI incompatibility (NOT fixable by user)

Even after fixing ISO9660, Docker's initd binary crashes:

dmesg: netlink: 'initd': attribute type 4 has an invalid length.
logs:  dial unix /run/host-services/backend.sock: connect: no such file or directory

The initd binary is compiled against kernel 6.6.x netlink headers. Kernel 6.18 changed the netlink attribute structures, causing an ABI mismatch that users cannot fix.

Confirmation

Reverting to the default WSL kernel (6.6.114.1) immediately fixes Docker Desktop.

Request

1. Documentation

Please document:

• Which WSL2 kernel versions are supported by Docker Desktop
• Which CONFIG_* options must be =y (built-in) for Docker Desktop to function
• That kernel= in .wslconfig affects the docker-desktop distro (many users don't realize this)

2. Compatibility improvement

Please consider one or more of:

• Recompile LinuxKit binaries for kernel 6.18+ ABI — Microsoft has already released linux-msft-wsl-6.18.y and users are adopting it
• Add a kernel version check in Docker Desktop startup that warns users when an incompatible kernel is detected (instead of the current silent infinite hang)
• Request a per-distro kernel override from Microsoft so docker-desktop can use the default kernel regardless of .wslconfig settings

3. Error messaging

Currently, the only indication of failure is:

ERROR: request returned 500 Internal Server Error for API route and version
http://%2F%2F.%2Fpipe%2FdockerDesktopLinuxEngine/v1.54/info

This tells the user nothing. A message like "Docker Desktop requires WSL2 kernel 6.6.x — detected incompatible kernel 6.18.x" would save users hours of debugging.

Debugging effort required

Diagnosing this issue took 4+ hours of manual investigation:

1. Reading com.docker.backend.exe.log (only shows "waiting for ping" — useless)
2. Exec into docker-desktop distro, finding no dockerd/containerd running
3. Running wsl-bootstrap manually to discover the ISO mount failure
4. Checking /proc/filesystems, /proc/config.gz, /lib/modules/
5. Recompiling kernel with ISO9660=y, re-testing
6. Finding the netlink ABI error in dmesg
7. Comparing full kernel configs (82 differences, none Docker-relevant)
8. Reverting to default kernel to confirm

None of this should be necessary. A startup check or documentation would prevent it entirely.

Call for collaboration between Docker and Microsoft WSL teams

This compatibility issue between Docker Desktop and WSL2 custom kernels is not new — it has been a recurring pain point for years, affecting every user who needs a custom kernel for development, security, or performance reasons. Each time Microsoft ships a new kernel branch, Docker Desktop breaks silently, and users are left alone to debug for hours with no guidance from either side.

We strongly encourage the Docker Desktop for Windows team to work directly with the Microsoft WSL team to resolve this once and for all. Specifically:

• Define a stable kernel ABI contract that Docker's LinuxKit binaries rely on, so that future kernel updates don't silently break Docker
• Coordinate release timelines — when Microsoft publishes a new linux-msft-wsl-* branch, Docker should be prepared to support it (or at minimum, detect it and warn users)
• Jointly propose a solution for custom kernels — whether that's a per-distro kernel override, a kernel compatibility shim, or Docker shipping its own kernel for its internal distro
• Publish a shared compatibility matrix so users know which kernel versions work with which Docker Desktop versions

The WSL custom kernel feature is officially supported and documented by Microsoft. Docker Desktop for Windows relies on WSL2 as its primary backend. These two products must work together seamlessly — the current situation where a user following Microsoft's official kernel compilation guide ends up with a completely broken Docker (with zero useful error messages) is unacceptable.

I have opened a parallel request on the Microsoft WSL repository: microsoft/WSL#40573

Related

• My bug report: docker info returns 500 Internal Server Error on API route /v1.54/info (Docker Desktop 29.4.3) for-win#15049
• Feature request (6.18 support): Feature request: Support WSL2 custom kernels 6.18+ (LinuxKit initd netlink ABI incompatibility) #397
• Microsoft WSL issue (same request, with /feature tag): Custom kernel from linux-msft-wsl-6.18.y branch silently breaks Docker Desktop — no documentation or warning microsoft/WSL#40573
• Full debugging procedure: docker info returns 500 Internal Server Error on API route /v1.54/info (Docker Desktop 29.4.3) valorisa/WSL2-Custom-Kernel-6.18-LTS-Guide#1

[valorisa]

/feature