WSL kernelDebugPort: Understand the Debugger Relay Before Enabling It

The current WSL configuration reference lists kernelDebugPort as a global [wsl2] setting. Its default is 0, which disables kernel debugging, and Microsoft describes a nonzero value as the port used by the Linux kernel debugger relay. That is the public contract. The configuration page does not provide a complete attach procedure, debugger transport diagram, symbol-matching recipe, or promise that every Microsoft-supplied or custom kernel contains the needed debug options.

That distinction is important. A port number in .wslconfig is not, by itself, proof that a host debugger can attach to the guest kernel. Kernel debugging requires compatible kernel configuration, a supported I/O path, matching symbols, and a debugger workflow that understands the WSL relay. A careful operator should establish those prerequisites before changing a global setting that affects the shared WSL 2 VM.

Read the documented setting literally

The reference puts kernelDebugPort in [wsl2], gives 0 as its default, and says it is the port used by the Linux kernel debugger relay. The page marks it as a Windows 11 setting. .wslconfig is global to WSL 2 distributions in the Windows user’s profile; it is not a per-distribution setting and has no effect on a WSL 1 environment in the same way.

The documented disabled state is:

[wsl2]
kernelDebugPort=0

Do not assume a nonzero example value such as 50000 is universally safe, reachable, or sufficient. The public config reference does not specify a reserved range, whether a given port must be free on the host, a named debugger command, or an attach handshake. Unless an official, version-matched Microsoft procedure tells you how to choose and consume the port for your environment, do not copy arbitrary values from third-party snippets.

Before any experiment, capture Windows build, WSL package version, kernel version, and current .wslconfig. Check whether device policy or an administrator controls the feature. Managed devices may disallow advanced runtime options; an unsupported setting that is silently ignored can look like a debugger failure. Preserve the existing file, make one change at a time, and keep a rollback copy outside WSL.

Kernel debugging has its own prerequisites

Linux’s upstream KGDB documentation describes a kernel debugging framework that requires the kernel to be built with the relevant configuration and connected through an I/O driver such as kgdboc. Its generic boot and runtime parameters are Linux kernel facilities; they are not proof that the WSL kernel build or WSL’s host-side relay implements a particular KGDB workflow.

Microsoft’s public WSL debugging documentation focuses on collecting WSL logs, inspecting kernel console output, debugging user-mode Linux processes, and using the supported WSL debug shell. Those diagnostics are distinct from attaching a source-level kernel debugger. A dmesg log can show boot or driver messages, but it does not provide interactive breakpoints or stack inspection. A user-process gdb session debugs that process, not the WSL kernel.

Likewise, WinDbg workflows for analyzing Linux crash dumps are postmortem analysis, not necessarily live kernel-debugger attachment. A crash dump, ETW trace, kernel console, user-mode trace, and live kernel-debugging session answer different questions. Select the artifact based on whether the failure is reproducible, whether the guest still runs, and whether the needed symbols and debugger path are available.

Do not conflate it with the other debug settings

WSL has separate documented diagnostics controls. debugConsole can show Linux kernel console output during startup. debugConsoleLogFile appends kernel console output to a Windows path. maxCrashDumpCount and crashDumpFolder govern retention and location of WSL crash dumps. The WSL debug shell supports recovery scenarios. These are not interchangeable with kernelDebugPort.

Use the least invasive tool that can answer the question. If the issue is early boot output, enable the documented console or log file. If a distro will not start, use the supported recovery workflow. If the WSL VM crashes, preserve the crash artifact and matching version data. Reserve live kernel debugging for cases where a source-level breakpoint or low-level state inspection is genuinely required and the official WSL-specific procedure is available.

Establish a safe experiment plan

Treat the setting as a lab-only change unless your organization has an approved and supported workflow for it. A disposable distribution does not fully isolate the change because .wslconfig affects the shared WSL 2 VM; the test can disrupt every WSL 2 distro on that Windows user. Stop stateful workloads cleanly and schedule a full VM restart. Keep a Windows-side recovery path so you can restore the previous configuration if WSL cannot start.

Before changing the file, record:

wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose
Get-Content "$env:USERPROFILE\.wslconfig" -ErrorAction SilentlyContinue

Also record the kernel reported by the target distro with uname -r if it starts, plus the exact reproduction command and host time. Do not treat the distro’s /proc/version string alone as a full symbol identity. For source-level analysis, debugger and symbols must match the running kernel build and configuration.

If an official workflow specifies a port, use the exact procedure for that WSL release. Confirm the chosen port does not collide with another host service using an approved Windows diagnostic, but do not publish listening endpoints or firewall exceptions broadly. This article intentionally does not invent a PowerShell attach command because the current public WSL config and debugging pages do not document one.

Verify observable outcomes, not intent

After applying an approved setup and restarting the VM, verify that WSL is healthy and that the intended debugger workflow reports a connection to the correct kernel instance. An open TCP port alone does not prove that a kernel-debug protocol is listening. A successful WSL launch alone does not prove that kernelDebugPort was honored. A debugger console without matching symbols may connect but still produce misleading addresses or unusable source views.

Use a controlled kernel test only if it cannot corrupt valuable data and the debugging procedure is supported. Prefer a deliberately instrumented lab kernel and a harmless, reversible trigger. Record expected and actual kernel build IDs, symbol files, debugger version, port/transport, and timestamps. If the only evidence is that the WSL setting parses, report the experiment as configuration validation, not successful kernel debugging.

When the problem cannot be reproduced safely, fall back to supported evidence collection: WSL diagnostic logs, kernel console output, a crash dump if WSL emitted one, and a minimal repro with version data. Avoid changing kernelCommandLine, custom kernel paths, and debugger port simultaneously because that makes it impossible to determine which control changed behavior.

Roll back explicitly

For normal use, kernelDebugPort=0 is the documented disabled state. Restore that value or remove the override, then stop the WSL 2 VM and verify the next launch. Because .wslconfig is global, communicate the shutdown window to anyone running background WSL services. Do not delete distributions, reinstall WSL, or change the kernel to undo a port experiment.

If no official version-specific attach instructions are available, leave the default disabled and pursue the supported logging or dump-analysis path. The absence of public operational details is a constraint to communicate, not an invitation to guess. The setting exists in the configuration table, but its presence alone does not establish a generally supported field workflow.

The useful takeaway is precise: kernelDebugPort names a relay port and 0 disables the feature. Everything beyond that requires a compatible WSL kernel build and a documented debugger workflow. Keep the setting off until those two prerequisites are established, and distinguish live kernel debugging from logs, user-mode debugging, and dump analysis.

Related:

Sources: