dotfiles

Troubleshooting

Quick checks for common issues.

Install and update

Problem: Install script fails immediately

• Verify that git and curl are installed.
• Check internet connectivity.
• Try running with verbose output: bash -x install.sh

Problem: Chezmoi apply fails

• Re-run chezmoi apply to re-sync state.
• Check for merge conflicts: chezmoi diff
• If hooks fail, check ~/.local/share/dotfiles.log for details.
• For non-interactive sessions, force apply to avoid TTY prompts: DOTFILES_NONINTERACTIVE=1 dot apply --force

Problem: Packages fail to install

• macOS: Verify Homebrew is installed and up to date (brew update)
• Linux: Run sudo apt-get update first
• Verify you have sufficient permissions

Shell startup

Problem: Shell is slow to start

• Run dot benchmark to measure startup time
• Profile with zsh -x to trace startup
• Check for slow plugins or large history files

Problem: Aliases or functions not available

• Run chezmoi apply to regenerate config files
• Source your shell config: source ~/.zshrc
• Verify the relevant tool is installed

Problem: dot doctor prints a directory listing instead of diagnostics

• This usually means dot was shadowed by a navigation alias in the current shell session.
• Check resolution: type -a dot
• Fix current session: unalias dot 2>/dev/null || true && exec zsh
• Validate after reload: dot doctor

Problem: Zsh reports it cannot write .zwc files

• Cause: stale read-only zsh cache files after an upgrade.
• Remove stale caches:
  • find ~/.config/shell ~/.config/zsh -type f -name '*.zwc' -delete
• Reload shell: exec zsh
• Re-run health checks: dot doctor

Problem: Shell crashes on startup

• Temporarily move ~/.zshrc and retry to isolate the fault
• Check for syntax errors: zsh -n ~/.zshrc
• Review recent changes: chezmoi diff

Secrets and encryption

Problem: Encrypted files fail to decrypt

• Confirm ~/.config/chezmoi/key.txt exists.
• Verify the key matches the one used for encryption.
• Re-initialize with dot secrets-init if needed.

Problem: Age encryption not working

• Verify age is installed: command -v age
• Check key permissions: ls -la ~/.config/chezmoi/key.txt (should be 600)

Neovim

Problem: Plugins fail to load

• Run :checkhealth in Neovim
• Update plugins: :Lazy sync
• Check for missing dependencies (node, python, etc.)

Problem: LSP not working

• Install required language servers
• Check :LspInfo for status
• Review :LspLog for errors

Git

Problem: Git aliases not working

• Check if Git config is applied: git config --list
• Re-apply dotfiles: chezmoi apply

Problem: Delta (diff pager) not showing colors

• Verify delta is installed
• Confirm your terminal supports 256 colors

Kubernetes tools

Problem: kubectl context issues

• List contexts: kubectl config get-contexts
• Switch context: kubectx <context-name>
• Check kubeconfig: echo $KUBECONFIG

Problem: Minikube won’t start

• Verify Docker is running
• Try: minikube delete && minikube start
• Check logs: minikube logs

Performance

Problem: High memory usage

• Look for runaway processes: htop or btop
• Review shell history size in atuin config
• Disable unused plugins

Common infrastructure failures

Problem: Nix isn’t installed or commands not found

• Ensure you have followed the installation guide: curl -L https://nixos.org/nix/install | sh
• On Linux, you might need to enable experimental features in ~/.config/nix/nix.conf: experimental-features = nix-command flakes
• Verify the daemon is running: ps aux | grep nix-daemon

Problem: Systemd isn’t available (mostly WSL2)

• Dotfiles functions that rely on systemd (like pueue management) will fallback to direct execution.
• To enable systemd in WSL2, add this to /etc/wsl.conf (requires Windows 11 or latest WSL):

  [boot]
  systemd=true
  

• Restart WSL: wsl.exe --shutdown

Problem: GPG or SSH signing fails

• Check if your key is present: gpg --list-secret-keys or ssh-add -l
• Ensure GPG_TTY is set (dotfiles does this automatically in rc.d).
• For hardware keys (Yubikey), ensure pcscd is running on Linux.

Advanced Troubleshooting

WSL2 and Nix Integration Issues

For complex WSL2 edge cases, Nix integration problems, and recovery procedures, see the comprehensive guide: WSL2 & Nix Troubleshooting Guide

This guide covers:

• WSL2 filesystem and networking edge cases
• Nix installation and flake management issues
• Complete system recovery procedures
• Performance optimization for WSL2/Nix environments
• Cross-platform migration scenarios

Still stuck

Open an issue with:

• OS + version
• Output of dot doctor (if available)
• Relevant log snippets from ~/.local/share/dotfiles.log
• Steps to reproduce the issue
• For WSL2/Nix issues: Include diagnostic report from the advanced guide

This site is open source. Improve this page.