Retaining WSL 2 Crash Dumps: Configure Locations, Limits, and Reproducible Evidence

When WSL 2 crashes, useful diagnostic data can be lost if its output directory is ephemeral, too small, or cleaned before an investigation begins. Current Microsoft configuration documentation lists crashDumpFolder as an absolute Windows path for WSL crash dumps and maxCrashDumpCount as a retention count. The documented default is %Temp%\wsl-crashes for the folder and 10 retained dump files for the count. Those settings are operational controls for WSL-generated crash dumps; they should not be confused with Linux applications’ user-space core files or with ordinary kernel console logs.

Design retention before reproducing a failure. Dumps can be large, count-based retention does not impose a byte quota, and moving a folder does not guarantee that every crash source will produce a dump. The useful result is a repeatable collection process with enough free space, a clear retention policy, and context that lets an engineer identify which WSL runtime and distro were involved.

Distinguish the diagnostic artifacts

There are several different files an operator may call a “core dump.” A Linux process can produce an ELF core file through the process core-dump mechanism. A WSL crash dump is a diagnostic artifact emitted by the WSL runtime for a WSL failure. Kernel console output, ETW traces, and application logs are different artifacts again. Microsoft’s Linux crash-dump guidance describes using WinDbg with Linux kernel or process dump data; it does not make maxCrashDumpCount a control for every Linux process’s ulimit -c, systemd-coredump, or application-specific crash writer.

Write down which failure class is under investigation. If one process segfaults while the distro remains healthy, first inspect the distro’s core-dump configuration and the application’s logs. If the WSL VM or subsystem itself crashes, configure and collect the WSL-level dump path. If the issue is a slow or failed startup with no crash, use WSL diagnostic logs and kernel console output rather than expecting a crash dump to appear.

The current WSL reference places crashDumpFolder and maxCrashDumpCount in the global [wsl2] settings. .wslconfig lives under the Windows user profile and affects WSL 2 rather than WSL 1. A changed configuration may require the WSL 2 VM to stop and restart. Record the exact WSL package version and Windows build because the set of settings available depends on the installed runtime.

Choose a durable, supportable Windows path

Choose a local Windows directory with adequate free space and access for the Windows account running WSL. Avoid pointing a live dump directory into a temporary cleanup area if the investigation may span a reboot. A synchronized or redirected folder can add latency, locking, or quota behavior; verify the actual filesystem and organization policy before using one. Keep the path stable and do not move or rename dump files while WSL is writing them.

For example, merge these values into the existing [wsl2] section of %UserProfile%\.wslconfig:

[wsl2]
crashDumpFolder=C:\\Users\\Example\\Documents\\WSL-Dumps
maxCrashDumpCount=20

The path is a Windows path. Microsoft’s configuration guidance requires escaped backslashes for path entries in .wslconfig; do not write a Linux path such as /home/user/dumps here. Choose a real directory for the active Windows user and validate that the runtime can access it. The example count of 20 is illustrative; it is not a sizing recommendation. The documented behavior is to remove older dump files when the configured count is exceeded.

Before changing the file, preserve unrelated memory, CPU, networking, kernel, and swap settings. If [wsl2] already exists, add the keys there instead of creating a duplicate section. To apply global settings, stop the WSL 2 VM in a maintenance window. wsl.exe --shutdown stops all WSL 2 distributions, which can interrupt services and in-flight writes. After restarting, capture wsl.exe --version, wsl.exe --status, the effective file contents, and a directory listing to document the test.

Retention count is not a storage budget

maxCrashDumpCount limits the number of retained WSL crash dump files according to the current reference. It does not specify a maximum size per file, a byte quota, or a guarantee that a fixed amount of space is sufficient. A small number of large dumps can still consume substantial disk space. Estimate storage from observed dump sizes and the likely incident frequency, then monitor free space at the selected path.

Do not set the count to zero or an extremely small number as a substitute for an evidence policy. Automatic deletion of older dumps may remove the artifact needed for a delayed escalation. Conversely, an unlimited or very large count can accumulate files until the host volume runs short. Retention should reflect the incident response window, acceptable disk use, and any independent archival process.

A simple PowerShell inventory can show file count, total bytes, newest write times, and free space without opening the dumps:

$dumpRoot = Join-Path $env:USERPROFILE 'Documents\WSL-Dumps'
$files = Get-ChildItem -LiteralPath $dumpRoot -File -ErrorAction Stop
$volumeDrive = [System.IO.Path]::GetPathRoot((Resolve-Path -LiteralPath $dumpRoot).Path)[0]
[pscustomobject]@{
    Directory = $dumpRoot
    FileCount = $files.Count
    TotalBytes = ($files | Measure-Object -Property Length -Sum).Sum
    NewestWriteUtc = ($files | Sort-Object LastWriteTimeUtc -Descending | Select-Object -First 1).LastWriteTimeUtc
}
Get-Volume -DriveLetter $volumeDrive | Select-Object DriveLetter, Size, SizeRemaining

The inventory path must match the path configured in .wslconfig. It reports current files, not a guarantee about future dump size. Include the count, total bytes, volume free space, and configuration in operational checks. If an automated cleanup process is used, exclude active files and preserve incident-relevant samples before deletion.

Pair a dump with enough context to interpret it

A dump without a version and reproduction record is often difficult to use. At the time of a failure, capture Windows build, WSL package version, distro name and release, kernel version if the distro starts, exact triggering command, time in UTC, whether the VM was cold or warm, and any custom kernel or modules. Preserve the WSL configuration relevant to the failure, but redact unrelated environment variables or secrets from logs before sharing.

For a Linux kernel or process dump, follow Microsoft’s current WinDbg Linux dump instructions and provide matching symbols and source where applicable. A WSL-level dump may need a different analysis path than an ELF application core. Do not assume gdb can read every WSL artifact or that a file extension alone identifies the dump format. Keep the original artifact immutable and work from a copy when debugging tools may modify state.

Kernel console output is useful but not a substitute for a dump. The WSL configuration reference separately lists debugConsoleLogFile for appending Linux kernel console output to a Windows path, and debugConsole for a console view on supported Windows/WSL versions. Use those facilities when the question concerns early boot messages. Avoid mixing these logs into the crash dump directory if a collector assumes every file there is a dump.

A safe collection test

Do not intentionally crash a valuable distro just to test retention. First validate the directory and configuration syntax, then use a disposable environment and a documented reproducible failure only if such a test is appropriate. Confirm that the runtime recognizes the setting, a produced artifact appears in the expected folder, the name and timestamp are recorded, and the configured count behavior is understood. If a controlled failure cannot be generated safely, mark artifact production as unverified rather than claiming the path is proven.

For a production incident, copy the relevant dump and accompanying metadata to a controlled evidence store before the automatic retention limit can remove it. Preserve original timestamps and compute a cryptographic hash if chain-of-custody matters. Redact user names or private path components in the copy only after preserving the original; do not edit the original evidence.

Operational checklist

Before enabling a longer retention window, confirm that the configured path is absolute and writable by the Windows account, the target volume has measured headroom, and the count is compatible with the expected analysis delay. After a WSL update, verify that the setting remains in the current reference and that the installed runtime uses the intended file. Check both file count and bytes on a schedule appropriate to the device, and periodically confirm that older dumps are not being removed by an unrelated cleanup policy.

The goal is not to retain every artifact forever. It is to preserve enough trustworthy diagnostic evidence for an investigation without turning crash collection into an unbounded disk consumer. Separate WSL runtime dumps, Linux process cores, kernel logs, and ETW traces; then keep each type with the toolchain and metadata needed to interpret it.

Related:

Sources: