So you've run into a bug while testing Ubuntu Focal Fossa on WSL, now what?

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 search the WSL GitHub issues for the error or name of the application you are having problems with?
  • Did you Google the name of the application you are having problems with + " WSL"?

The Sorting Hat

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

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

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

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 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 then getting a bug report from a user that is clearly upset but doesn't provide us enough information to help them. It is also not uncommon to have a user report a bug, have it get closed, and the user 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:

  • You need to search for the problem first, both in the respective bug reports and on Google.
  • You need to attempt some troubleshooting and information gathering yourself.
  • You should provide a full and detailed bug report.
  • 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:

##windows-wsl on Freenode IRC

/r/bashonubuntuonwindows

Bug reporting etiquette

Awesome-WSL

The Ubuntu lifecycle and release cadence