Troubleshooting

WSL Installation Issues

Error: "WSL 2 requires an update to its kernel component"

Solution: Download and install the WSL2 kernel update:

1. Go to aka.ms/wsl2kernel
2. Download and run the MSI installer
3. Restart your computer

Error: "Virtual Machine Platform not enabled"

Solution: Enable virtualisation in PowerShell (Admin):

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Then restart your computer.

WSL is extremely slow

Cause: Working with files on Windows drives (/mnt/c/).

Solution: Keep your projects in the Linux filesystem (~):

mkdir -p ~/projects && cd ~/projects

Terminal Issues

Icons display as boxes or question marks

Cause: Nerd Font not configured in Windows Terminal.

Solution:

1. Open Windows Terminal Settings (Ctrl+,)
2. Go to Profiles > Ubuntu > Appearance
3. Set Font face to your Nerd Font (e.g., "JetBrainsMono Nerd Font")
4. Click Save

Terminal starts in wrong directory

Solution: Set the starting directory in Windows Terminal:

1. Open Settings > Profiles > Ubuntu > General
2. Set Starting directory to ~
3. Turn off "Use parent process directory"

Bootstrap Script Issues

Script exits partway through

Cause: A component failed to install.

Solution: The script now continues past failures and reports them at the end. Check the warnings and install any failed components manually.

Permission denied errors

Cause: Sudo password required.

Solution: Enter your Linux password when prompted. Remember, you won't see characters as you type.

pip install errors (externally-managed-environment)

Cause: Ubuntu 24.04 blocks system-wide pip installs (PEP 668).

Solution: Use uv tool install instead of pip for global tools:

uv tool install poetry

Tool-Specific Issues

Command not found after installation

Solution: Reload your shell configuration:

source ~/.bashrc

Or simply close and reopen your terminal.

zoxide: "no match found"

Cause: zoxide doesn't know about that directory yet.

Solution: Visit the directory first with cd, then zoxide will remember it. You can also add directories manually:

zoxide add ~/projects/myapp

Git push asks for username/password

Cause: Using HTTPS URL instead of SSH.

Solution: Change to SSH URL:

git remote set-url origin [email protected]:username/repo.git

Make sure you've set up SSH keys (see Git SSH setup).

Starting Fresh

If things are really broken, you can reset your Ubuntu installation:

wsl --unregister Ubuntu-24.04

Then reinstall:

wsl --install -d Ubuntu-24.04

Getting More Help

If you're still stuck:

• Open an issue on GitHub with details about your problem
• Search for your error message - someone else has probably encountered it
• Check the Microsoft WSL troubleshooting docs