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.

I was recently testing the ZSH shell on my WSL instance and decided to make it default. After removing it with Apt my WSL instance suddenly wouldn't start up. After investigating, I realized that WSL was failing to start a session for my user using a now nonexistent ZSH shell. Strangely enough, Apt/Ubuntu ignored that my system still had references to that shell. My expectation is that it would have reverted the user sessions back to bash what didn't happen.

In case you're interested, here's how to reproduce the error:

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

But before we jump to the solution, it's important to understand some how WSL works in the background.

WSL Background

WSL is run by Windows as the wsl.exe executable file located on c:\windows\system32. That executable bootstraps the whole Linux subsystem on your machine using files located on your Windows disk. Knowing where the files used by your WSL instance are located is a good start to troubleshooting. On my machine, they're found on:

C:\Users\<my-user>\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\rootfs

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 

You should then see a generic help for your instance:

However if WSL is broken any additional information will not be output on the console. So, it's important to have some context on the issue before we can fix it. On my particular case, since I knew my default shell (ZSH) was failing to load, 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

Testing

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.

References

• Ubuntu - Changing Shells
• Windows command line reference available
• Linux apps are coming to Chromebooks
• Troubleshooting Windows Subsystem for Linux

See Also

• My journey to 1 million articles read
• Windows Subsystem for Linux, the best way to learn Linux on Windows 
• 5 tools for Azure Development on Linux
• How to copy data between Azure databases
• How to create a Ubuntu Desktop instance on Azure
• How to build and run ASP.NET Core on Linux
• Creating ASP.NET Core websites with Docker
• Send emails from ASP.NET Core websites using SendGrid and Azure
• Why I use Fedora Linux
• How I fell in love with i3

For more posts about WSL on this blog, please click here.