WSL Kernel Boot Output: Use debugConsole and debugConsoleLogFile Deliberately

When a WSL 2 distribution fails before a usable Linux shell appears, an ordinary journalctl query may be too late in the startup chain to explain the failure. The global .wslconfig reference documents two kernel-console facilities for that earlier window: debugConsole opens a console showing dmesg when a distro instance starts, and debugConsoleLogFile appends Linux kernel console output to an absolute Windows path. They are useful for a controlled reproduction, but they are not substitutes for WSL ETW traces, application logs, or crash dumps. Choosing the right evidence source and keeping it separate prevents an early boot message from being mistaken for a complete platform trace.

Distinguish the evidence channels

Linux dmesg displays messages from the guest kernel’s ring buffer when the guest is running and the caller has permission. debugConsole is a WSL configuration option that displays the contents of dmesg as a WSL 2 distro instance starts. debugConsoleLogFile is documented separately as a file path to which Linux kernel console output is appended. Neither setting captures the full Windows-side WSL lifecycle, all user-space service logs, or a structured memory dump.

ETW is a Windows tracing system and can capture WSL platform events around VM and distribution startup. WSL’s diagnostic collector and Windows Performance Analyzer are more appropriate when the failure involves the WSL service, VM creation, or Windows networking path. A Linux journal is useful after systemd and the distro have progressed far enough to record events. A crash dump serves a different purpose: postmortem memory and process inspection. Keep these products distinct in an incident report.

The debugConsole key is listed as Windows 11-only in Microsoft’s current .wslconfig table. The current table lists debugConsoleLogFile as an absolute Windows path but does not mark it with the same footnote. Do not infer that the two keys have identical minimum-version requirements. Capture wsl --version and Windows build, then validate a setting on the target platform before making it a dependency.

Capture a baseline before enabling output

Record the failing distro, whether it is WSL 1 or WSL 2, the WSL package version, Windows build, exact launch command, local timestamp and time zone, and whether the issue occurs after a cold Windows start or a warm WSL restart. If a different distro starts, record that as a comparison rather than proof that every shared component is healthy.

From Windows, save the current config and determine whether another WSL session is keeping the VM alive:

wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose
wsl.exe --list --running
Copy-Item "$env:USERPROFILE\.wslconfig" `
  "$env:USERPROFILE\.wslconfig.pre-debug" -ErrorAction SilentlyContinue

Do not replace the file with a sample: it may already contain a custom kernel, memory or network controls, crash-dump paths, or settings owned by workstation management. Add the diagnostic key to the existing [wsl2] section and preserve all other values.

Enable the interactive console for a short reproduction

For a Windows 11 host with a supported current WSL package, a focused configuration is:

[wsl2]
debugConsole=true

Restart WSL so the configuration is read for a new VM or distro instance. Closing one terminal can leave the shared VM alive, so first identify active distros. Use wsl --shutdown only after stopping databases, containers, and other important processes because it ends all WSL sessions. Then start the one distro and observe the console during the reproduction.

Treat the console as a narrow live view of startup kernel messages, not as a guaranteed transcript of every component. Record the timestamp and preserve relevant lines with enough surrounding context to show sequence. A console that closes or contains no warning does not prove the kernel is healthy; the failure can occur outside the captured output window, in distribution initialization, a systemd unit, a mount, or Windows-side WSL services.

Write kernel console output to a Windows-side file

If a console window is inconvenient or the startup failure is intermittent, configure debugConsoleLogFile with an absolute Windows path:

[wsl2]
debugConsoleLogFile=C:\\Users\\Example\\AppData\\Local\\Temp\\wsl-kernel-console.log

Microsoft documents that console output is appended to the specified file. That means operators should plan for the log to grow across starts: use a dedicated path, collect a baseline size, and establish a rotation or cleanup procedure appropriate to the diagnostic period. Do not point it at the same directory used by automated crash-dump processing if that process assumes every file is a dump. Do not store it in a shared or synchronized location without reviewing the contents and retention requirements.

An absolute path is required by the documented setting. In .wslconfig, Windows path separators must be escaped as shown in Microsoft’s examples. Confirm the directory exists and that the Windows account can write to it; then start a controlled instance and verify the file timestamp and length change. A configured path alone is not evidence that the setting was recognized. If it remains empty, re-check the exact filename, profile, section, WSL version, restart boundary, and actual boot event.

Kernel messages can disclose device details, filesystem names, network state, and host-specific paths. Treat them as diagnostic artifacts. Preserve an original copy before filtering or redacting, and share only the minimum evidence approved for the support channel. Console logs are not necessarily safe to publish just because they lack application-level passwords.

Correlate with guest and Windows evidence

If the distribution reaches a shell, collect a bounded guest-side comparison:

uname -a
date --iso-8601=seconds
dmesg --ctime | tail -n 200

On a systemd-enabled distro, collect the boot journal separately:

journalctl -b -p warning --no-pager
systemctl --failed --no-pager

These commands show different stages and can use different clock representations. In particular, Linux dmesg --ctime converts kernel timestamps to wall-clock form, but its manual warns that the converted time can be inaccurate for messages around system suspend/resume. Treat it as a readable aid, not a definitive cross-host timestamp; preserve the raw kernel time where exact ordering matters and record the Windows-side reproduction time and time zone for ETW correlation. A kernel console line that appears before a failed mount can guide the next test, but the later mount error still needs its own evidence. Do not treat a clean dmesg excerpt as a complete startup health check.

For a platform-level failure, use Microsoft’s maintained WSL diagnostic collection path and a suitable trace profile, then inspect the ETL with Windows Performance Analyzer. A full platform trace can contain sensitive information and produce large files; use it only when the simpler kernel output cannot locate the failure. If WSL crashes, use the supported dump workflow for that diagnosis instead of assuming console logs contain enough state to analyze memory corruption.

Avoid confusing a kernel boot issue with a distribution-start timeout

WSL exposes separate global wait controls for the kernel and for distribution startup, and a separate per-distro initTimeout for systemd initialization. A kernel console message can help determine whether the guest kernel began booting, but the presence of output does not establish that the kernel completed initialization or that systemd is ready. Measure the affected boundary and consult the focused timeout guidance before extending any deadline.

If there is no useful output, consider whether the setting took effect, the console output window was missed, or the failure occurred in another layer. Check WSL versions, reproduce after a full restart, and compare a known-good distro. Avoid changing timeout values, custom kernels, and debugging settings together; one variable per test preserves causal evidence.

For intermittent failures, define an artifact naming convention that includes the date, WSL package version, distro, and reproduction identifier, then copy the append-only log to a separate immutable incident folder after each run. Preserve the raw file before extracting a few relevant lines. Without a per-run copy, output from several starts can be interleaved and make it unclear which warning belongs to the failing attempt. Add the launch timestamp from Windows to the incident record and keep enough context before and after the suspicious event; a lone kernel line rarely establishes causation.

If a failure appears only on one Windows host, capture the same short boot on a known-good machine with the same distro and WSL package where possible. Compare kernel release, Windows build, custom .wslconfig values, and attached devices before drawing a conclusion. A text difference in console output can narrow a lead, but absence of a line on one machine is not conclusive evidence that the underlying component never ran. Repeat the controlled start and corroborate with ETW or guest logs when the failure layer remains ambiguous.

Disable diagnostics when the investigation closes

After collecting enough evidence, remove debugConsole or the log path from .wslconfig, restart WSL, and confirm that routine sessions behave as intended. Archive the minimum relevant artifact with version and reproduction metadata, apply the organization’s retention rules, and delete temporary copies when their approved retention expires. Leave a note describing which key was used and when it was removed so another engineer does not mistake a temporary diagnostic setting for a supported permanent baseline.

The investigation is complete only when the original symptom is reproduced or disproved, kernel output is correlated with the exact launch attempt, the appropriate guest/Windows evidence is preserved, and the diagnostic configuration has a rollback. These facilities make early boot more observable; they do not replace a layer-specific diagnosis.

Related:

Sources: