Troubleshooting

Common issues and solutions.

Command Not Found

Symptom

Tool installed but command not found

Check PATH

echo $PATH | tr ':' '\n'

Should include:

• ~/.local/bin
• /usr/local/bin (macOS) or /usr/bin (Arch) for the Node.js system package
• /usr/local/bin or /opt/homebrew/bin (macOS)

Fix: Reload shell

source ~/.config/zsh/.zshrc
# or
exec zsh

Neovim Issues

Plugins won't load

nvim -c "Lazy sync" -c "qa"    # Force sync
rm -rf ~/.local/share/nvim/lazy/  # Clear cache

LSP not working

:LspInfo                # Check attached servers
:checkhealth vim.lsp    # Run diagnostics

Version too old

nvim --version          # Should be 0.11+
brew upgrade neovim     # macOS

Symlink Issues

Config file not updating

ls -la ~/.config/zsh/.zshrc  # Check symlink
symlinks relink macos        # Recreate symlinks

Theme Issues

Theme not applying

theme current           # Check current theme
theme verify            # Check theme system
theme apply <name>      # Apply theme directly

Tmux colors wrong

# In tmux
Ctrl+Space r            # Reload tmux config

Git Issues

Git identity not set

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Credential helper not working (macOS)

git config --global credential.helper osxkeychain

Package Manager Issues

Homebrew slow/hanging (macOS)

brew update             # Update package lists
brew doctor             # Check for issues
brew cleanup            # Clean old versions

apt package not found (Ubuntu)

sudo apt update         # Update package lists

Some tools need cargo install or manual installation on Ubuntu. See Platform Differences.

WSL-Specific

ZDOTDIR not working

Check /etc/zshenv (macOS) or /etc/zsh/zshenv (Ubuntu/WSL):

cat /etc/zshenv

Should contain:

export ZDOTDIR="$HOME/.config/zsh"

Still Having Issues?

Check git history (git log --oneline) for recent changes that may have introduced issues.