How to Triage and Report WSL-Related Issues

Basic Steps

This applies to any WSL-related issue:

  • Did you consult the documentation, such as the Ubuntu Wiki or Microsoft Docs?
  • Did you Google the error message?
  • Did you Google the name of the application you are having problems with + " WSL"?
  • Did you search the WSL GitHub issues for the error or name of the application you are having problems with?
  • Is this an inherent limitation of WSL? Is it a limitation of WSL1 that would be fixed by switching to WSL 2?

The Sorting Hat

To determine where to submit a bug, we must figure out what is breaking:

  • If it is an issue when upgrading from 18.04 or using apt on 20.04, then report it as a general Ubuntu WSL bug.

  • If it is an issue when running wslusc, wslsys, wslfetch, wslvar, or wslview in Ubuntu, then report it as a bug on the Ubuntu version of wslutilities.

  • If it is a security issue, such as privilege escalation, malware, Windows Defender-related bugs, or results in a Green Screen of Death, then e-mail your bug report to secure@microsoft.com.

  • If it is an issue with the new Windows Terminal, such as rendering issues or mouse supports, then report it as a Terminal bug.

  • If it is an issue with WSL networking, Linux/Windows interoperability, or running binaries on WSL1, and can be reproduced on different WSL distros, then report it as a general WSL bug.

Help Us Help You

There is nothing more frustrating than getting a bug report from a user that is clearly upset but doesn’t provide us enough information to help them. It is also sadly common to have a user report a bug, have it closed, and the user does not understand why or feel like they were short-changed by the maintainer.

Here are some key things we need from you as maintainers when you are filing a bug report so that we can properly respond to your bug report:

  • You need to search for the problem first, both in the respective bug reports locations (see above) and on Google.
  • You need to attempt some troubleshooting and information gathering yourself.
  • You should provide a full and detailed bug report (see below).
  • You may need to be patient as bugs are investigated and sorted.

We need to know specifically for WSL:

  • A title succinctly describing the issue
  • Your version and build of Windows:
ver.exe
  • Your version of WSL:
wsl.exe --list --all --verbose
  • Steps to reproduce:
1. Download Ubuntu from Microsoft Store
2. sudo apt install hello-world
3. hello-world

The goal here is to provide a minimal, complete, and verifiable example of the problem that can be reproduced by our engineers.

  • What you expect to happen:
An explanation of what you expected to happen here. For example, hello-world returned 'Hello World!'
  • What actually happens:
An explanation of what is happening here instead. For example, hello-world segfaults.
  • If an application is failing to run, export an strace and upload to a saved to a pastebin or gist
strace -o some_command.strace -f some_command some_args
  • A list of what you have attempted to do so solve or document the bug, including workarounds

Other helpful information you can include:

  • Name of the package involved, e.g. ebtables
  • A screenshot of the error using the Snipping Tool or Snip & Sketch in Action Center
  • Logs saved to a Pastebin or Github Gist
  • If you are having problems launching WSL, more detailed logs may be necessary
  • A temporary workaround you found

This information and some patience will allow us to better serve our users when bugs arise.

Additional tips:

  • Limit each report to one issue at a time
  • Use bullet points to summarize
  • Do not lost lengthy logs in your report, use a Pastebin or Github Gist
  • Use code snippets and formatting where needed to improve readability
  • Use footnotes [1] for lengthy digressions

More resources:

2 Likes

C:\WINDOWS\system32>wsl.exe --list --all --verbose
Windows Subsystem for Linux Distributions:
Ubuntu-18.04 (Default)
Debian
Ubuntu-20.04

Shell command “sleep” does not work. Issue for example: sleep 5
results in “sleep: cannot read realtime clock: Invalid argument”.
Script or command line should pause for 5 seconds.

This worked fine under 18.04.

Thank you