Custom kernel from linux-msft-wsl-6.18.y branch silently breaks Docker Desktop — no documentation or warning

[valorisa]

Custom kernel 6.18.y from linux-msft-wsl-6.18.y branch breaks Docker Desktop — documentation needed

Summary

Compiling and using a custom WSL2 kernel from the official linux-msft-wsl-6.18.y branch following the standard procedure (cp Microsoft/config-wsl .config && make) results in a kernel that completely breaks Docker Desktop. The failure is silent — no useful error in Docker UI, no hint that the kernel is the problem — and requires hours of manual debugging inside the docker-desktop distro to diagnose.

There is currently no documentation warning users about this incompatibility, nor any guide explaining which kernel options must be built-in (=y) or which kernel versions are compatible with Docker Desktop.

Request

Please provide:

1. A compatibility notice on the linux-msft-wsl-6.18.y branch README stating that Docker Desktop is not yet compatible with this kernel version
2. A "Custom Kernel Guide" documenting:
   • Which CONFIG_* options MUST be =y (not =m) for Docker Desktop to function (at minimum: CONFIG_ISO9660_FS)
   • Which kernel branches are compatible with Docker Desktop (currently only 6.6.y works)
   • The fact that kernel= in .wslconfig is global and affects ALL distros including docker-desktop
   • The fact that WSL2 never populates /lib/modules/, making any CONFIG_*=m effectively dead code
3. A recommended config fragment for Docker Desktop compatibility (similar to how Docker provides check-config.sh for Linux hosts)

Environment

Component	Version
Windows	11 Enterprise 10.0.26200
WSL	2.7.3.0
Default kernel	6.6.114.1-microsoft-standard-WSL2
Custom kernel	6.18.20.3-microsoft-standard-WSL2+ (from linux-msft-wsl-6.18.y)
Docker Desktop	4.73.0 (build 226246)
Docker Engine	29.4.3

Problem Description

What I did

1. Cloned microsoft/WSL2-Linux-Kernel branch linux-msft-wsl-6.18.y
2. Used the official config: cp Microsoft/config-wsl .config
3. Compiled: make olddefconfig && make -j$(nproc) bzImage
4. Configured .wslconfig:

   [wsl2]
   kernel=C:\\wsl-kernels\\6.18.20.3\\bzImage

5. Ran wsl --shutdown and restarted Docker Desktop

What happened

Docker Desktop shows "Starting the Docker Engine..." indefinitely. The engine never starts. docker info returns HTTP 500.

Debugging (4+ hours)

The failure has two layers, both undocumented:

Layer 1 — Missing ISO9660 filesystem (silent failure)

The default Microsoft/config-wsl sets CONFIG_ISO9660_FS=m (module). Since WSL2 never provides /lib/modules/, this module can never be loaded. Docker Desktop's wsl-bootstrap needs to mount two ISO images during startup:

$ wsl -d docker-desktop -u root -- /usr/local/bin/wsl-bootstrap run [...]
mount: unknown filesystem type 'iso9660'

No error appears in Docker Desktop UI. You must run wsl-bootstrap manually to see this.

Evidence:

$ wsl -d docker-desktop cat /proc/filesystems | grep iso
# (no output)

$ wsl -d docker-desktop zcat /proc/config.gz | grep ISO9660
CONFIG_ISO9660_FS=m

$ wsl -d docker-desktop ls /lib/modules/
ls: No such file or directory

Layer 2 — Kernel ABI incompatibility (netlink)

After recompiling with CONFIG_ISO9660_FS=y, the ISOs mount correctly but Docker's LinuxKit initd binary fails:

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

Docker Desktop's initd is compiled against kernel 6.6.x netlink headers. The netlink attribute structures changed in 6.18, causing an ABI mismatch that cannot be fixed by kernel config alone.

What works

Reverting to the default kernel (commenting out kernel= in .wslconfig) immediately fixes Docker Desktop:

$ docker info | grep "Kernel Version"
 Kernel Version: 6.6.114.1-microsoft-standard-WSL2

Why this matters

1. The linux-msft-wsl-6.18.y branch exists on the official Microsoft repo — users reasonably expect it to work with the WSL2 ecosystem including Docker Desktop
2. The default Microsoft/config-wsl is broken for Docker — CONFIG_ISO9660_FS=m is unusable since modules don't work in WSL2
3. Error messages are completely misleading — Docker shows "HTTP 500" and "engine not responding", nothing about kernels or filesystems
4. kernel= in .wslconfig is a footgun — it silently affects docker-desktop distro with no way to exempt it
5. Hours of debugging required — the only way to diagnose this is to manually exec into docker-desktop, run wsl-bootstrap by hand, and check dmesg

Proposed solutions

Short term

• Add a compatibility warning to the linux-msft-wsl-6.18.y README
• Fix Microsoft/config-wsl to set CONFIG_ISO9660_FS=y (not =m) — since modules are dead code in WSL2, there's no reason to use =m for anything

Medium term

• Provide a "Docker Desktop compatible" config fragment or a validation script
• Document the .wslconfig kernel= global scope and its impact on Docker Desktop
• Consider adding a per-distro kernel override mechanism (so docker-desktop can use the default kernel while other distros use a custom one)

Long term

• Coordinate with Docker to ensure LinuxKit binaries support kernel 6.18+ netlink ABI
• Or provide a kernel compatibility layer / stable ABI guarantee for the netlink interface

Related issues

• Docker for Windows: docker info returns 500 Internal Server Error on API route /v1.54/info (Docker Desktop 29.4.3) docker/for-win#15049 (my report)
• Docker feature request for 6.18 support: Feature request: Support WSL2 custom kernels 6.18+ (LinuxKit initd netlink ABI incompatibility) docker/desktop-feedback#397
• Full debugging procedure and kernel config comparison: 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

Kernel config comparison (relevant excerpt)

Both kernels were compared (/proc/config.gz from default 6.6 vs .config from custom 6.18). All Docker-critical options (namespaces, cgroups, netfilter, overlay, virtio, 9p) are identical. The only Docker-relevant difference is:

- CONFIG_ISO9660_FS=m    # default 6.6 (works because default kernel has it built differently)
+ CONFIG_ISO9660_FS=y    # custom 6.18 (after manual fix)

The initd failure is NOT a config issue — it's a kernel ABI incompatibility between 6.18 netlink structures and Docker's binaries compiled for 6.6.

Reproduction steps

# 1. Compile kernel from linux-msft-wsl-6.18.y using Microsoft/config-wsl
# 2. Set kernel= in .wslconfig pointing to the new bzImage
# 3. wsl --shutdown
# 4. Start Docker Desktop
# 5. Observe infinite "Starting the Docker Engine..." spinner
# 6. Run: docker info → HTTP 500

Expected: Docker Desktop works, OR a clear error message indicating kernel incompatibility.
Actual: Silent infinite hang with misleading HTTP 500 error.

[github-actions]

Logs are required for review from WSL team

If this a feature request, please reply with '/feature'. If this is a question, reply with '/question'.
Otherwise, please attach logs by following the instructions below, your issue will not be reviewed unless they are added. These logs will help us understand what is going on in your machine.

How to collect WSL logs

Download and execute collect-wsl-logs.ps1 in an administrative powershell prompt:

Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-wsl-logs.ps1" -OutFile collect-wsl-logs.ps1
Set-ExecutionPolicy Bypass -Scope Process -Force
.\collect-wsl-logs.ps1

The script will output the path of the log file once done.

If this is a networking issue, please use .\collect-wsl-logs.ps1 -LogProfile networking instead, following the instructions in Collect WSL logs for networking issues

Once completed please upload the output files to this GitHub issue.

See Collect WSL logs (recommended method).

If you choose to email these logs instead of attaching them to the bug, please send them to wsl-gh-logs@microsoft.com with the GitHub issue number in the subject, and include a link to your GitHub issue comment in the message body, and reply with '/emailed-logs'.

[github-actions]

Diagnostic information

Found '/feature', adding tag 'feature'

[valorisa]

/feature

[github-actions]

Diagnostic information

Found '/feature', adding tag 'feature'

[onomatopellan]

Hi, modules are part of the custom kernel compilation since a while. You need to use a script to generate the VHDX containing the modules.
You can take a look at my gist for how to compile custom 6.x kernel in https://gist.github.com/onomatopellan/c5220c0efddaff69aaff77cca80b7b8e

edit: I forgot to say all this is in the official repository.

[valorisa]

Thanks @onomatopellan for the pointer! I'm actually already building and installing modules via make modules_install (as shown in my guide). The Layer 1 issue (ISO9660) can indeed be fixed either by building the VHDX with modules or by setting CONFIG_ISO9660_FS=y directly.

However, the core problem in this issue is Layer 2 — even with modules working correctly and ISO9660 available, Docker Desktop's initd binary fails with:

netlink: 'initd': attribute type 4 has an invalid length.

This is a kernel ABI incompatibility: Docker's LinuxKit binaries are compiled against 6.6.x netlink headers, and the netlink attribute structures changed in 6.18. No kernel config change can fix this — it requires Docker to update their binaries for 6.18+ compatibility.

So the feature request stands: users need either (1) a compatibility warning on the 6.18.y branch, or (2) a per-distro kernel override so docker-desktop can keep using the default 6.6 kernel while other distros use a custom one.

[valorisa]

@onomatopellan Thanks again for your detailed response — your Waydroid gist is excellent work, and the kernelModules= VHDX approach is a clean solution for making =m modules actually loadable in WSL2.

However, I think there's a gap between our two contexts that's worth clarifying:

Your context: Custom kernel for Waydroid/Android Binder — you need specific modules loaded, the VHDX mechanism solves that perfectly, and Waydroid doesn't care about kernel ABI changes since it ships its own userspace.

My context: Custom kernel 6.18 + Docker Desktop coexistence. The problem has two layers:

1. Layer 1 (modules/ISO9660): Yes, your VHDX approach would solve this — if CONFIG_ISO9660_FS=m, mounting the modules VHDX would make it loadable. But setting CONFIG_ISO9660_FS=y directly is simpler and achieves the same result without the extra VHDX step. Either way, Layer 1 is solvable.

2. Layer 2 (kernel ABI — the real blocker): Even with all modules working perfectly and ISO9660 available, Docker Desktop's LinuxKit initd binary crashes with:

   netlink: 'initd': attribute type 4 has an invalid length.
   

   Docker's binaries are compiled against 6.6.x netlink structures. The netlink attribute format changed in 6.18 at the kernel level — no module loading strategy or config change can fix this. It requires Docker to recompile their binaries for 6.18+ ABI compatibility.

The fundamental difference: Your solution enables custom modules to load (great for Waydroid, which ships its own compatible binaries). My problem is that a third-party vendor (Docker) ships precompiled binaries that are ABI-incompatible with kernel 6.18 — and there's nothing we can do on the kernel side to fix that.

Unfortunately, until either Docker updates their LinuxKit binaries for 6.18+, or Microsoft adds a per-distro kernel= override (so docker-desktop distro can stay on 6.6 while others use 6.18), users who need both Docker Desktop and a 6.18 custom kernel are stuck.

That said, I'll definitely document the kernelModules= VHDX mechanism in my guide — it's valuable knowledge for anyone building custom kernels with module dependencies. Thanks for sharing it!

[onomatopellan]

Thanks, now I understand better the issue with custom kernels.
Do you have the issue with the kernel of the official WSL pre-release 2.7.5? With every new WSL release the team opens a thread in the Discussions section so users can discuss about things that got broken. The last pre-release 2.7.5 is the first one that contains kernel 6.18.x so I recommend to post the Docker issue there.

[valorisa]

Great suggestion @onomatopellan! I haven't tested WSL 2.7.5 pre-release yet, but since its kernel is also 6.18.x, the same netlink ABI issue with Docker Desktop should reproduce — the problem is between Docker's LinuxKit binaries (compiled for 6.6.x) and any 6.18+ kernel, regardless of whether it's custom-built or Microsoft's official one.

I'll install 2.7.5 pre-release, confirm the issue there, and post in the discussion thread as you recommended. That's probably the right place to get visibility from the WSL team on this Docker incompatibility. Thanks for pointing me there!