.dotfiles

Troubleshooting Guide

Solutions for common setup and configuration issues

Quick Diagnostics

# Run comprehensive health check
nvim +checkhealth
brew doctor

# Individual component checks
brew doctor                      # Homebrew issues
nvim +checkhealth               # Neovim configuration
tmux info                       # tmux server status
echo $SHELL                     # Current shell

Installation Issues

Homebrew Problems

Cannot install in Homebrew on ARM processor

# Solution: Ensure correct architecture
arch -arm64 brew install <package>  # Apple Silicon
arch -x86_64 brew install <package> # Intel/Rosetta

Permission denied errors

# Fix Homebrew permissions
sudo chown -R $(whoami) $(brew --prefix)/*
brew doctor

No formulae found

# Update Homebrew
brew update
brew tap homebrew/core

Shell Configuration

Command not found after installation

# Reload shell configuration
exec zsh -l

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

# Check shell
echo $SHELL
which zsh

Zinit not loading

# Verify installation
ls -la ~/.local/share/zinit

# Reinstall if needed
rm -rf ~/.local/share/zinit
exec zsh  # Will auto-reinstall

# Check plugin loading
zinit status

Neovim Issues

Plugins not installing

# In Neovim
:Lazy sync
:Lazy clean
:Lazy restore

# Clear cache
rm -rf ~/.local/share/nvim
rm -rf ~/.cache/nvim

Issue: LSP servers not working

# In Neovim
:LspInfo
:Mason
:MasonInstallAll

# Manual installation
:MasonInstall pyright lua-language-server

Issue: Treesitter errors

# In Neovim
:TSUpdate
:TSInstall! all

tmux Problems

Issue: “server not found” error

# Kill all tmux sessions
tmux kill-server

# Start fresh
tmux new -s main

Terminal Display Issues

Issue: Broken characters/icons

# Verify font installation
fc-list | grep -i "nerd"

# Reinstall fonts
brew reinstall --cask font-fira-code-nerd-font
brew reinstall --cask font-jetbrains-mono-nerd-font

# Clear font cache
sudo atsutil databases -remove

Issue: Colors not displaying correctly

# Check terminal capabilities
echo $TERM
infocmp $TERM | grep -E "colors|RGB"

# Set correct TERM
export TERM=xterm-256color  # or alacritty

Performance Issues

Slow Shell Startup

# Profile zsh startup
time zsh -i -c exit

# Detailed profiling
zsh -xvf 2>&1 | ts -i "%.s" > /tmp/zsh-startup.log

# Check for slow plugins
zinit times

Neovim Startup Time

" Profile startup
:StartupTime

" Disable plugins temporarily
:Lazy profile

" Check specific plugin
:Lazy load <plugin-name>

High CPU Usage

# Identify culprit
htop

# Common causes:
# - Language servers
# - File watchers
# - Background indexing

Git Configuration Issues

Issue: “fatal: not a git repository”

# Initialize git in dotfiles
cd ~/.dotfiles
git init
git remote add origin https://github.com/IllyaStarikov/.dotfiles.git

Issue: Delta not working

# Verify installation
which delta

# Check git config
git config --get core.pager

# Reinstall
brew reinstall git-delta

Theme Switching Problems

Issue: Theme not changing

# Manual theme switch
~/.dotfiles/src/theme/switch-theme.sh

# Check theme files
ls -la ~/.config/alacritty/theme.toml
ls -la ~/.config/tmux/theme.conf

# Reset theme cache
rm -rf ~/.cache/theme

Issue: Partial theme application

# Force reload all components
killall tmux
theme

# In Neovim
:source $MYVIMRC

Network-Related Issues

Issue: Package downloads failing

# Check DNS
scutil --dns

# Use alternative DNS
sudo networksetup -setdnsservers Wi-Fi 8.8.8.8 8.8.4.4

# Reset DNS cache
sudo dscacheutil -flushcache

Issue: SSL certificate errors

# Update certificates
brew install ca-certificates
brew link --force ca-certificates

# For Python
pip install --upgrade certifi

Recovery Procedures

Complete Reset

# Backup current config
mv ~/.dotfiles ~/.dotfiles.backup

# Fresh installation
git clone https://github.com/IllyaStarikov/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./src/setup/install.sh

Partial Reset

# Reset Neovim
rm -rf ~/.config/nvim ~/.local/share/nvim ~/.local/state/nvim
cd ~/.dotfiles && ./src/setup/symlinks.sh

# Reset tmux
rm -rf ~/.tmux/plugins
tmux kill-server
cd ~/.dotfiles && ./src/setup/symlinks.sh

# Reset shell
rm ~/.zshrc ~/.oh-my-zsh
cd ~/.dotfiles && ./src/setup/install.sh

Debug Mode

Enable Verbose Logging

# Shell debugging
set -x  # Enable
set +x  # Disable

# Neovim debugging
nvim -V9nvim.log

# Git debugging
GIT_TRACE=1 git <command>

Getting Help

Diagnostic Information

When reporting issues, include:

# System info
sw_vers
uname -a
arch

# Tool versions
brew --version
nvim --version
tmux -V
zsh --version

# Configuration
echo $SHELL
echo $PATH

Resources

• Homebrew Troubleshooting
• Neovim FAQ
• tmux FAQ
• Zinit Documentation

---

← Back to Setup

This site is open source. Improve this page.