A comprehensive troubleshooting guide for WSL2 edge cases, Nix integration issues, and recovery procedures for failed installations.
# Check if symlinks are enabled
ls -la ~/.dotfiles/
# Look for broken symlinks (red entries)
Root Cause: Windows filesystem doesn’t support Unix symlinks by default.
Solutions:
# Run in PowerShell as Administrator
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# Move dotfiles to WSL2 filesystem
cd ~
git clone https://github.com/sebastienrousseau/dotfiles.git .dotfiles
git config --global core.symlinks true
git config --global core.autocrlf false
# Test filesystem performance
time ls -la /mnt/c/Users/
time ls -la ~/
Solution: Always work within WSL2 filesystem (~/) for performance-critical operations.
# Check mount options
mount | grep drvfs
Solution: Remount with proper permissions:
# Create /etc/wsl.conf
sudo tee /etc/wsl.conf > /dev/null <<EOF
[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"
mountFsTab = false
EOF
# Restart WSL2 from Windows PowerShell
wsl --shutdown
# Test DNS resolution
nslookup github.com
ping github.com
Solutions:
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo tee /etc/wsl.conf > /dev/null <<EOF
[network]
generateResolvConf = false
EOF
sudo tee /etc/resolv.conf > /dev/null <<EOF
nameserver 1.1.1.1
nameserver 8.8.8.8
EOF
# Check if port is bound
netstat -tulpn | grep :3000
Solution: Use Windows port proxy:
# Run in PowerShell as Administrator
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=172.x.x.x
# Check WSL2 memory usage
cat /proc/meminfo | grep MemTotal
free -h
Solution: Limit WSL2 memory usage:
# Create %UserProfile%\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=2GB
Solution: Compact WSL2 virtual disk:
# Run in PowerShell as Administrator
wsl --shutdown
diskpart
# select vdisk file="C:\Users\%USERNAME%\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\ext4.vhdx"
# attach vdisk readonly
# compact vdisk
# detach vdisk
# exit
# Check if installation attempted
ls -la /nix/
which nix
Solutions:
curl -L https://nixos.org/nix/install | sh -s -- --daemon
sudo chown -R $(whoami) /nix/var/nix/profiles/per-user/$(whoami)/
sudo chmod -R 755 /nix/var/nix/profiles/per-user/$(whoami)/
sudo tee /etc/wsl.conf > /dev/null <<EOF
[boot]
systemd=true
EOF
# Test flakes support
nix flake --help
Solution: Enable experimental features:
mkdir -p ~/.config/nix/
tee ~/.config/nix/nix.conf > /dev/null <<EOF
experimental-features = nix-command flakes
trusted-users = $(whoami)
EOF
# Or globally
sudo tee /etc/nix/nix.conf > /dev/null <<EOF
experimental-features = nix-command flakes
trusted-users = @wheel
EOF
# Test Nix store access
nix ping-store
Solutions:
sudo apt update && sudo apt install ca-certificates
export NIX_SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
echo 'export NIX_SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt' >> ~/.bashrc
# Check flake lock status
cd ~/.dotfiles/nix/
nix flake check --impure
Solution: Update and rebuild lock file:
cd ~/.dotfiles/nix/
rm flake.lock
nix flake update
nix flake check
# List Nix profiles
nix profile list
# Check which packages are shadowing system ones
which -a git
Solutions:
nix profile remove <profile-number>
nix profile install nixpkgs#git --priority 10
cd ~/.dotfiles/nix/
nix develop
# Check store integrity
nix-store --verify --check-contents
Solution: Repair corrupted store:
# Stop Nix daemon
sudo systemctl stop nix-daemon
# Repair store
sudo nix-store --verify --check-contents --repair
# Restart daemon
sudo systemctl start nix-daemon
# Test cache connectivity
nix ping-store --store https://cache.nixos.org
Solution: Configure trusted substituters:
sudo tee -a /etc/nix/nix.conf > /dev/null <<EOF
substituters = https://cache.nixos.org/ https://nix-community.cachix.org
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=
EOF
# Check Nix store size
du -sh /nix/store/
df -h /nix/
Solution: Clean up Nix store:
# Remove unused packages
nix-collect-garbage
# Deep cleanup (removes old generations)
nix-collect-garbage -d
# Optimize store (hard link identical files)
nix-store --optimise
# 1. Backup current state
cp ~/.zshrc ~/.zshrc.backup.$(date +%s)
cp ~/.bashrc ~/.bashrc.backup.$(date +%s)
# 2. Reset to minimal shell
export PATH=/usr/bin:/bin
unset ZDOTDIR
# 3. Clean chezmoi state
rm -rf ~/.local/share/chezmoi/
rm -rf ~/.config/chezmoi/
# 4. Reinstall from scratch
cd /tmp
curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh | bash
# From Windows PowerShell as Administrator
# 1. Export current installation (backup)
wsl --export Ubuntu Ubuntu-backup.tar
# 2. Unregister broken installation
wsl --unregister Ubuntu
# 3. Reinstall from Microsoft Store or import backup
wsl --import Ubuntu C:\WSL\Ubuntu Ubuntu-backup.tar
# 4. Reinstall dotfiles
wsl -d Ubuntu -u root -- curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh | bash
# 1. Remove broken Nix
sudo rm -rf /nix/
sudo userdel -r nix-daemon 2>/dev/null || true
sudo groupdel nixbld 2>/dev/null || true
# 2. Clean environment
unset NIX_PATH
unset NIX_PROFILES
unset NIX_SSL_CERT_FILE
# 3. Reinstall Nix
curl -L https://nixos.org/nix/install | sh
# 4. Restart shell and test
exec zsh
which nix
# 1. Use emergency shell config
cat > ~/.zshrc.emergency <<'EOF'
export PATH=/usr/bin:/bin:/usr/sbin:/sbin
export SHELL=/bin/zsh
alias ll='ls -la'
alias la='ls -la'
PS1='%n@%m:%~$ '
EOF
# 2. Test emergency config
zsh -c 'source ~/.zshrc.emergency && echo "Emergency config works"'
# 3. Gradually restore
mv ~/.zshrc ~/.zshrc.broken
ln -s ~/.zshrc.emergency ~/.zshrc
# 4. Reinstall dotfiles piece by piece
cd ~/.dotfiles
chezmoi init --force
chezmoi apply --dry-run
chezmoi apply
# 1. Check if key file exists
ls -la ~/.config/chezmoi/key.txt
# 2. If missing, try to recover from backup locations
find / -name "key.txt" -type f 2>/dev/null
find /mnt/c/ -name "*.key" -type f 2>/dev/null
# 3. Test key validity
age -d -i ~/.config/chezmoi/key.txt ~/.local/share/chezmoi/encrypted_file.age
# 4. If key is lost, regenerate encrypted files
chezmoi execute-template --init --force
# 1. Check current git config
git config --list --show-origin
# 2. Backup current config
cp ~/.gitconfig ~/.gitconfig.backup.$(date +%s)
# 3. Restore from dotfiles
chezmoi apply --include='**/dot_gitconfig*'
# 4. Verify critical settings
git config --get user.name
git config --get user.email
git config --get core.editor
# 1. Move frequently accessed files to WSL2 filesystem
mkdir -p ~/workspace
ln -s ~/workspace ~/workspace
# 2. Configure Git for performance
git config --global core.preloadindex true
git config --global core.fscache true
git config --global gc.auto 256
# 3. Use native WSL2 paths in tools
export BROWSER="/mnt/c/Program Files/Mozilla Firefox/firefox.exe"
export EDITOR="nvim"
# 1. Limit shell history
echo 'HISTSIZE=1000' >> ~/.zshrc
echo 'SAVEHIST=1000' >> ~/.zshrc
# 2. Disable unnecessary services
sudo systemctl disable apache2 2>/dev/null || true
sudo systemctl disable mysql 2>/dev/null || true
# 3. Configure swap usage
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
# Configure build settings
sudo tee -a /etc/nix/nix.conf > /dev/null <<EOF
max-jobs = auto
cores = 0
sandbox = true
substituters = https://cache.nixos.org/ https://nix-community.cachix.org
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
EOF
# Install and configure cachix
nix profile install nixpkgs#cachix
cachix use nix-community
# Add to shell config
echo 'eval "$(cachix completion bash)"' >> ~/.bashrc
# 1. Check path differences
echo $PATH | tr ':' '\n' | sort
# 2. Check shell differences
echo $SHELL
zsh --version
# 3. Check package managers
which brew 2>/dev/null && echo "Homebrew found"
which apt 2>/dev/null && echo "APT found"
which nix 2>/dev/null && echo "Nix found"
# 1. Export current configuration
cd ~/.dotfiles
chezmoi archive --format=tar | gzip > dotfiles-backup.tar.gz
# 2. Transfer to WSL2 (from Windows side)
# Copy dotfiles-backup.tar.gz to Windows, then:
# cp /mnt/c/Users/username/Downloads/dotfiles-backup.tar.gz ./
# 3. Import on WSL2
tar -xzf dotfiles-backup.tar.gz
cd ~/.dotfiles
git remote update
git pull origin main
# 4. Platform-specific adjustments
chezmoi apply --dry-run
chezmoi apply
# Check systemd status
systemctl is-system-running 2>/dev/null || echo "systemd not available"
# Alternative service management for WSL2
sudo service ssh start # Instead of systemctl start ssh
# 1. Export network settings from source system
ip route show > network-config.txt
cat /etc/resolv.conf >> network-config.txt
# 2. Adapt for WSL2
# (WSL2 handles most networking automatically)
# 1. Access via different shell
/bin/bash --noprofile --norc
# 2. Or use emergency profile
export PATH=/usr/bin:/bin
export PS1="EMERGENCY $ "
export SHELL=/bin/bash
# 3. Fix basic functionality
alias ls='ls --color=auto'
alias ll='ls -la'
# From Windows PowerShell as Administrator
# 1. Check WSL2 status
wsl --status
# 2. Restart WSL2 service
net stop LxssManager
net start LxssManager
# 3. If that fails, restart Docker Desktop (if installed)
# Then restart WSL2
# 4. Last resort: restart Windows
# System information
cat /etc/os-release
uname -a
wsl.exe --version 2>/dev/null || echo "Not in WSL2"
# Nix information
nix --version 2>/dev/null || echo "Nix not installed"
nix-env --version 2>/dev/null || echo "nix-env not available"
# Dotfiles information
cd ~/.dotfiles && git log --oneline -5
chezmoi --version 2>/dev/null || echo "Chezmoi not installed"
# Generate diagnostic report
cat > ~/diagnostic-report.txt <<EOF
Date: $(date)
User: $(whoami)
Shell: $SHELL
OS: $(cat /etc/os-release | grep PRETTY_NAME)
Kernel: $(uname -r)
WSL Version: $(wsl.exe --version 2>/dev/null || echo "Not in WSL2")
Nix Version: $(nix --version 2>/dev/null || echo "Not installed")
Chezmoi Version: $(chezmoi --version 2>/dev/null || echo "Not installed")
Recent Git Commits:
$(cd ~/.dotfiles && git log --oneline -5 2>/dev/null || echo "Git not available")
Current PATH:
$(echo $PATH | tr ':' '\n' | nl)
Nix Profiles:
$(nix profile list 2>/dev/null || echo "Nix profiles not available")
WSL Mount Points:
$(mount | grep drvfs || echo "No Windows mounts")
EOF
echo "Diagnostic report saved to ~/diagnostic-report.txt"
# System status
dot doctor # Run dotfiles health check
wsl --status # WSL2 status
nix profile list # List Nix packages
chezmoi status # Chezmoi status
# Quick fixes
chezmoi apply # Reapply dotfiles
source ~/.zshrc # Reload shell config
nix-collect-garbage # Clean Nix store
sudo systemctl restart nix-daemon # Restart Nix daemon
# Emergency access
/bin/bash --noprofile # Clean shell
export PATH=/usr/bin:/bin # Minimal PATH
# Nuclear options (use with caution)
rm -rf ~/.local/share/chezmoi/ # Reset chezmoi
sudo rm -rf /nix/ # Remove Nix completely
wsl --unregister Ubuntu # Reset WSL2 (from PowerShell)
This guide covers the most common WSL2 and Nix edge cases. For issues not covered here, refer to the specific tool documentation or create a support request with the diagnostic information provided.
Before reporting issues, verify your environment with these commands:
# WSL2 Environment Check
echo "=== WSL2 Environment Check ==="
uname -a
cat /proc/version | grep -i wsl || echo "Not running in WSL2"
mount | grep drvfs | head -3
df -h / /tmp
# Nix Installation Check
echo "=== Nix Installation Check ==="
command -v nix && nix --version || echo "Nix not installed"
echo $NIX_PATH
ls -la ~/.config/nix/ 2>/dev/null || echo "No Nix config directory"
# Dotfiles Status Check
echo "=== Dotfiles Status Check ==="
command -v chezmoi && chezmoi --version || echo "Chezmoi not installed"
cd ~/.dotfiles && git status --porcelain || echo "Not in dotfiles directory"
ls -la ~/.dotfiles/nix/flake.nix 2>/dev/null || echo "Nix flake not found"
# Performance Check
echo "=== Performance Check ==="
time ls ~/.dotfiles >/dev/null
free -m 2>/dev/null || vm_stat | head -5
Run this checklist and include the output when requesting support.