Solved: Docker Desktop Unexpected WSL Error

Docker Desktop allows users to develop, manage, and share dockerized applications, but a few, when launching the app, received the Unexpected WSL error.

It could be encountered both on Windows and Mac, though we have seen more instances on the former. Most users who recently came across the Docker Desktop – Unexpected WSL error message were running Windows 11.

What is the WSL2 error in Docker Desktop?

WSL2 errors with Docker Desktop indicate either misconfigured permissions or the absence of critical components, especially the Virtual Machine Platform, an optional feature in Windows.

Also, if WSL itself is not installed, no WSL commands will be executed. And even network issues were reported to be an underlying cause by many. 

How do I fix unexpected WSL error on Docker Desktop?

Before we delve into the slightly complex solutions, try these quick ones:

• Verify whether your device meets the minimum requirements for Docker Desktop.
• Restart the PC. If you have to reboot every time to get Docker Desktop running, try the other solutions.
• Check for available updates and install the latest version of Docker Desktop from the official website. Also, update the operating system. It helped many who came across the An unexpected error occurred. Restart Docker Desktop message.
• Make sure Docker Desktop is running with administrative privileges to eliminate any access rights issues. This also helps when Docker Desktop takes forever to start.
• Disable any third-party antivirus on the PC. 

If none work, head to the fixes listed next.

1. Install WSL

1. Press Windows + S to open Search, type Command Prompt in the search bar, and click Run as administrator. 
2. Click Yes in the UAC prompt.
3. Now, paste the following command and hit Enter to install WSL: wsl --install
4. Once done, reboot the PC and check for improvements.

If Windows Subsystem for Linux is not installed, you will receive the Docker Desktop – Unexpected WSL error. After you do it, also enable Hyper-V on the device. Docker Desktop must run.

2. Update WSL

1. Press Windows + R to open Run, type cmd, and hit Ctrl + Shift + Enter.
2. Click Yes in the prompt that appears.
3. Paste the following command and hit Enter to update WSL: wsl --update
4. If any updates are installed, restart the PC.

3. Modify the settings.json file

1. Press Windows + E to open File Explorer, paste the following path in the address bar and hit Enter: %Appdata%\Docker
2. Double-click the settings.json file.
3. Now, make sure it reads the following:
   "integratedWslDistros" : [ ]
"enableIntegrationWithDefaultWslDistro" : false
4. If required, make the necessary edits and save the changes.
5. Once done, relaunch the project, and it shouldn’t throw the Docker Desktop failed to start WSL2 error anymore.

4. Change the Command Prompt settings

1. Press Windows + S to open Search, type Command Prompt, right-click on the relevant result and select Run as administrator. 
2. Click Yes in the UAC prompt that appears.
3. Now, right-click on the top bar, and select Properties from the context menu.
4. Go to the Options tab, tick the checkbox for Use legacy console, and click OK to save the changes.

Read more about this topic

• With upcoming GUI support, managing distros in WSL will be a breeze
• Uihost.exe: Complete Guide to Fix Application Errors
• 6 Best Tools to Fix Corrupt Archive Files in Windows
• How to Fix the OR-RWE-03 Payment Error on Google Play
• Operation Canceled Due to Restrictions in Excel 2010 [Fix]

5. Reset winsock

1. Press Windows + R to open Run, type cmd, hold Ctrl + Shift keys, and click OK. 
2. Click Yes in the prompt.
3. Now, paste the following two commands individually and hit Enter after each to reset the corrupt or misconfigured network settings: netsh int ip reset netsh winsock reset
4. Restart the PC and check whether the Docker Desktop failed to start error goes away.

6. Enable Hardware Virtualization in BIOS

1. Turn off your computer, then power it on, and as soon as the display appears, keep pressing the F2, F10, F12, Esc or Del key to access the BIOS, depending on the system manufacturer.
2. Now, use the arrow keys to go to the Advanced or System Configuration tab, and then select Virtualization Technology.
3. Finally, choose Enable, then save the changes and exit the BIOS.

It’s vital to enable Virtualization support on the PC for Docker Desktop to work properly. In the absence of this, you may receive the Docker Desktop – Unexpected WSL error.

7. Reinstall WSL

1. Press Windows + I to open Settings, go to Apps from the navigation pane, and click on Installed apps on the right. 
2. Now, locate Windows Subsystem for Linux, click the ellipsis next to it, and select Uninstall.
3. Again, click Uninstall in the confirmation prompt.
4. Similarly, remove the following entries under installed apps if these exist:
   • Linux
   • Ubuntu
5. Now, go back to the Apps tab, and select Optional features.
6. Click on More Windows features at the bottom.
7. Untick the checkbox for Virtual Machine Platform and Windows Subsystem for Linux, then click OK to save the changes.
8. Restart the computer for the changes to apply.
9. Once done, reinstall WSL (Windows Subsystem for Linux).

When nothing else works, you can always reinstall WSL and get rid of the Docker Desktop – Unexpected WSL error. Start by uninstalling WSL and then re-download all the components.

What is the alternative for Docker Desktop in Windows WSL?

There are several alternatives for Docker Desktop, and many users have been switching to these, given the recent changes to the project’s license terms. Here are the popular options:

• Rancher Desktop
• Minikube
• Podman

When switching to another software, verify compatibility with your OS, feature set, performance, ease of use, support team efficiency, and how often updates are released.

You must have eliminated the Docker Desktop – Unexpected WSL error by now. And if that’s not the case, wait for an update or switch to a reliable alternative. You know all the options!

Also, other installation errors affect users. For instance, many encountered the Hyper-V and container Windows features must be enabled error while installing Docker Desktop, but it’s easy to fix!

If you’re an administrator, don’t miss our guide on how to install Docker on Windows Server for more useful information.

For any queries or to share what worked for you, comment below.