Monday, July 15, 2019

Diagnosing and Fixing WSL initialization issues

After uninstalling ZSH from my Ubuntu WSL instance, my system wouldn't start. How to fix it? Let's take a look.

Understanding the Problem

My WSL user had ZSH shell set as default. After removing it with Apt the instance wouldn't start up. Why? The system still had references to the now nonexistent ZSH shell.

Strangely enough, Apt/Ubuntu ignored that users in my system had dependencies on that shell. My expectation is that they would have reverted the user sessions back to bash what didn't happen. As a result, opening WSL from the command line caused it to crash because my user had Zsh as default on my /etc/passwd.

Steps to Reproduce

  1. Install a new shell to your user (ex. zsh)
  2. Set it to your default (for example by using chsh but the zsh install script already does so)
  3. Uninstall that shell
Before we jump to the solution, let's review some WSL background.

WSL Background

In order to fix the issue, it's important to know some WSL background. WSL is run by Windows as the wsl.exe executable file located on c:\windows\system32. It's also important to know that the whole Linux subsystem it abstracts is located on your machine.

With that said, it's important to understand where the WSL files your Linux instance uses are located. On mine, they can be found on:
On yours, it could be equal or very similar. Definitely on your user's AppData\Local\Packages folder.

Fixing the Issue

Because wsl.exe is an executable, we can run it on the console. In order to do so, open a windows terminal and:
  1. cd into c:\windows\system32 
  2. run wsl --help 

Now you should see:

The downside is that if WSL is broken any additional information will be output on the console. So, it's important to have some context on the issue before we can fix it. On my case, to fix the issue I just had to change my user's shell to bash as the root user. That's as simple as:
  1. log in WSL as root
  2. As root, use chsh to change your user's shell

Logging in as Root from the Terminal in WSL

To login as root from the terminal, simply run the following command:
C:\Windows\System32>wsl -u root

Changing the User shell with chsh

Next we change the shell using chsh. chsh is a GNU utility created to chang the user shell. After logged in as root, one simply has to run the command:
chsh -s /bin/bash bruno


To test, you either have to close WSL (^D) and reopen it or as root, ron run su <user> on the current shell:
su bruno

Final Thoughts

Despite WSL not emitting much information on failures, it's important to remember that there's still a Linux system behind it. Knowing Linux or searching Linux related articles could help.It's also important to remember that, because all the filesystem is located on your C drive, you still have access to logs/config files and could try to fix from there if necessary.


See Also

For more posts about WSL on this blog, please click here.
Any comment or suggestion about this post? Please DM me on Twitter at @BrunoHilden