Skip to main content

WSL troubleshooting

Beginner
Getting started
Tutorial

The IC SDK is not natively supported on Windows operating systems. It is recommended for Windows users to install Windows Subsystem for Linux.

This page includes some common troubleshooting methods for common errors when using WSL.

Important notes​

  • Not all features of the IC SDK may be supported on WSL 2.

  • It is recommended to use WSL 2 instead of WSL 1.

  • Windows 11 is preferred as it has better support for WSL 2.

Troubleshooting​

Node.js is not properly installed​

WSL 2 has Node.js 10.x.x installed by default. But the latest IC SDK requires Node.js 16.x.x or 18.x.x.

Permission denied when running dfx start​

dfx commands must be run on the Linux filesystem instead of the Windows filesystem. It is recommended to use the commands cd ~ or cd $HOME from within the WSL terminal to bring you to the home directory, where dfx commands should work properly.

No internet access on WSL​

If you don’t have internet access on WSL, such that you cannot ping any server successfully, the nameserver on WSL may be set to an internal WSL proxy. You can check the /etc/resolv.conf file to see if that's the case. If it’s true, please follow the below steps to set to a valid nameserver:

  • Step 1: Create the /etc/wsl.conf file and add the following content:
  [network]
  generateResolvConf = false

This will prevent WSL from regenerating the /etc/resolv.conf file after restarting.

  • Step 2: Modify the nameserver in the /etc/resolv.conf file to a valid one, for example the Google nameserver 8.8.8.8.

  • Step 3: On Windows, restart WSL to apply this fix.

wsl.exe --shutdown