Troubleshooting

This guide covers common issues encountered when using WSL2 for development and their solutions.

1. WSL2 installation issues

1.1. Virtualisation not enabled

Symptom: WSL2 fails to start with virtualisation errors.

Solution:

  1. Restart your computer and enter BIOS settings

  2. Enable virtualisation:

    • Intel: Enable "Intel VT-x" or "Intel Virtualization Technology"

    • AMD: Enable "AMD-V" or "SVM Mode"

  3. Save and exit BIOS

Verify virtualisation is enabled:

  • Open Task Manager → Performance → CPU

  • Look for "Virtualisation: Enabled"

1.2. WSL2 kernel not installed

Symptom: Error message about WSL2 kernel.

Solution:

wsl --update
wsl --set-default-version 2

1.3. Distribution running as WSL1

Symptom: wsl --list --verbose shows VERSION as 1.

Solution:

wsl --set-version Ubuntu-24.04 2

2. Performance issues

2.1. Slow file operations

Symptom: Git, npm, Maven commands are extremely slow.

Cause: Projects located on Windows filesystem (/mnt/c/).

Solution:

Move projects to the native WSL2 filesystem:

# Copy project from Windows to WSL2
rsync -av --exclude='node_modules' --exclude='target' \
  /mnt/c/Users/<username>/projects/my-app/ \
  ~/dev/my-app/

# Or clone fresh
cd ~/dev
git clone [email protected]:owner/repo.git
Location Performance

~/dev/ (native)

Fast (native Linux I/O)

/mnt/c/ (Windows)

10-50x slower (9P protocol overhead)

2.2. WSL2 consuming too much memory

Symptom: Windows becomes slow; vmmem process using high memory.

Solution:

  1. Create or edit C:\Users\<YourUsername>\.wslconfig:

    [wsl2]
memory=8GB

[experimental]
autoMemoryReclaim=gradual

  2. Restart WSL2:

    wsl --shutdown

Check current memory usage:

free -h

2.3. Slow Windows Defender scanning

Symptom: File operations slow even on native filesystem.

Solution:

Add Windows Defender exclusions (run PowerShell as Administrator):

Add-MpPreference -ExclusionPath "\\wsl$\"
Add-MpPreference -ExclusionProcess "vmmem"
Add-MpPreference -ExclusionProcess "wsl.exe"

3. Networking issues

3.1. Cannot access localhost services from Windows

Symptom: Service running in WSL2 not accessible at localhost:port.

Solution:

  1. Ensure localhostForwarding is enabled in .wslconfig:

    [wsl2]
localhostForwarding=true

  2. Restart WSL2:

    wsl --shutdown

  3. Alternatively, use the WSL2 IP address:

    ip addr show eth0 | grep inet
# Access via the IP shown, e.g., 172.x.x.x:port

3.2. IntelliJ cannot connect to WSL2

Symptom: IntelliJ shows connection errors when opening WSL2 projects.

Solution:

  1. Check WSL2 is running:

    wsl --list --verbose

  2. Configure Windows Firewall:

    New-NetFirewallRule -DisplayName "Allow IntelliJ WSL2" `
    -Direction Inbound -Protocol TCP -Action Allow `
    -RemoteAddress 172.16.0.0/12

  3. Check firewall rules:

    Get-NetFirewallProfile -Name Public |
    Get-NetFirewallRule |
    Where-Object DisplayName -ILike "IntelliJ*"

3.3. VPN conflicts

Symptom: WSL2 loses network connectivity when VPN is active.

Solution:

Try mirrored networking mode in .wslconfig:

[wsl2]
networkingMode=mirrored

Then restart WSL2:

wsl --shutdown

Mirrored networking requires Windows 11 22H2 or later.

4. Git issues

4.1. Line ending problems

Symptom: Files showing as modified immediately after clone; Git shows ^M characters.

Solution:

Configure Git to use LF line endings:

git config --global core.autocrlf input
git config --global core.eol lf

Fix existing files:

# Install dos2unix
sudo apt install dos2unix

# Convert a single file
dos2unix filename.java

# Convert all Java files
find . -name "*.java" -exec dos2unix {} \;

4.2. SSH key not working

Symptom: Permission denied (publickey) when cloning.

Solution:

  1. Check SSH agent is running:

    eval "$(ssh-agent -s)"

  2. Add your key:

    ssh-add ~/.ssh/id_ed25519

  3. Verify the key is added:

    ssh-add -l

  4. Test GitHub connection:

    ssh -T [email protected]

  5. If still failing, check key is added to GitHub:

    cat ~/.ssh/id_ed25519.pub
# Copy this to GitHub → Settings → SSH Keys

4.3. Git credentials not persisting

Symptom: Asked for credentials repeatedly.

Solution:

Use SSH instead of HTTPS for GitHub:

# Check current remote
git remote -v

# Change to SSH
git remote set-url origin [email protected]:owner/repo.git

5. Maven build issues

5.1. JAVA_HOME not set

Symptom: Maven cannot find JDK; JAVA_HOME is not set error.

Solution:

Set JAVA_HOME permanently:

echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
source ~/.bashrc

# Verify
echo $JAVA_HOME
mvn --version

5.2. Out of memory during build

Symptom: Build fails with OutOfMemoryError.

Solution:

  1. Increase WSL2 memory in .wslconfig:

    [wsl2]
memory=12GB
swap=8GB

  2. Set Maven memory options:

    export MAVEN_OPTS="-Xmx2g -XX:MaxMetaspaceSize=512m"

  3. Restart WSL2 and try again.

6. IDE issues

6.1. VS Code extensions not loading

Symptom: Extensions show "Install in WSL" but don’t work.

Solution:

  1. Ensure you’re connected to WSL2 (check status bar shows "WSL: Ubuntu")

  2. Reinstall extensions in WSL2 context:

    • Open Extensions panel (Ctrl+Shift+X)

    • Click "Install in WSL: Ubuntu" for each extension

6.2. IntelliJ cannot find JDK

Symptom: "JDK not found" or "Invalid JDK path".

Solution:

Use the correct UNC path:

  1. Open File Explorer

  2. Navigate to \\wsl$\Ubuntu\usr\lib\jvm\

  3. Note the exact JDK directory name

  4. Use this path in IntelliJ: \\wsl$\Ubuntu\usr\lib\jvm\java-21-openjdk-amd64

6.3. IntelliJ terminal not using WSL2

Symptom: Terminal opens PowerShell or CMD instead of Bash.

Solution:

Configure terminal in Settings:

  1. Open Settings (Ctrl+Alt+S)

  2. Navigate to Tools → Terminal

  3. Set Shell path to: wsl.exe -d Ubuntu

  4. Click OK and open a new terminal

7. General troubleshooting commands

7.1. Check WSL2 status

# List distributions and versions
wsl --list --verbose

# Check WSL version
wsl --version

# Check status
wsl --status

7.2. Restart WSL2

wsl --shutdown
# Then start again by opening Ubuntu or running: wsl

7.3. Check filesystem location

pwd
# Should be /home/<user>/... not /mnt/c/...

7.4. Monitor resource usage

# Memory
free -h

# Disk
df -h

# Processes
htop  # Install with: sudo apt install htop

8. Getting help

If you encounter issues not covered here:

  1. Check the Microsoft WSL Documentation

  2. Search WSL GitHub Issues

  3. For IntelliJ issues, check JetBrains Issue Tracker

  4. For Claude Code issues, check Claude Code GitHub