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.
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:
- ##windows-wsl on Freenode IRC
- /r/bashonubuntuonwindows
- Bug reporting etiquette
- Awesome-WSL
- The Ubuntu lifecycle and release cadence