@sebastienrousseau/dotfiles/docs/guides/TROUBLESHOOTING.md

The Trusted Shell Platform — Universal dotfiles managed by Chezmoi. Features Bash & Zsh for macOS, Linux & WSL. Rust modern tooling & enterprise-grade security.

---
render_with_liquid: false
---

# 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):

  ```ini
  [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](WSL2_NIX_TROUBLESHOOTING.md)**

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