Troubleshooting

This guide helps resolve common issues with the dotfiles installation and configuration.

Installation Issues

Setup Script Permission Denied

Problem: Cannot execute setup script

Solution:

# Make script executable
chmod +x setup/setup-osx.sh
chmod +x setup/setup-debian.sh

# Run with bash
bash setup/setup-osx.sh

Homebrew Installation Fails (macOS)

Problem: Homebrew won't install

Solutions:

1. Install Command Line Tools:

xcode-select --install

2. Manual Homebrew Install:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Check Homebrew path:

# Apple Silicon (M1/M2)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

# Intel Mac
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile

apt Repository Issues (Debian/Ubuntu)

Problem: Package installation fails

Solutions:

1. Update package lists:

sudo apt update

2. Fix broken packages:

sudo apt --fix-broken install

3. Reinstall WakeMeOps repository:

curl https://raw.githubusercontent.com/upciti/wakemeops/main/assets/install_repository | sudo bash

4. Check sources:

cat /etc/apt/sources.list.d/wakemeops.list

oh-my-zsh Installation Fails

Problem: oh-my-zsh won't install

Solutions:

1. Manual install:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

2. Remove existing installation:

rm -rf ~/.oh-my-zsh
# Run setup again

3. Check Git availability:

git --version
# Install if missing

Package Installation Fails

Problem: Specific package won't install

Solutions:

1. Install manually:

# Homebrew
brew install <package>

# apt
sudo apt install <package>

2. Skip package and continue:

# Edit setup script to comment out failing package
vim setup/setup-osx.sh

3. Check package availability:

# Homebrew
brew search <package>

# apt
apt search <package>

Shell Issues

Command Not Found

Problem: Installed command not found

Solutions:

1. Restart shell:

exec zsh

2. Check PATH:

echo $PATH

3. Locate command:

# Find where command is installed
which <command>
find / -name <command> 2>/dev/null

4. Add to PATH:

# Add to ~/.zshrc
export PATH="/path/to/bin:$PATH"
source ~/.zshrc

Slow Shell Startup

Problem: Shell takes long to start

Solutions:

1. Profile startup:

time zsh -i -c exit

2. Disable plugins one by one:

# Edit ~/.zshrc
# Comment out plugins gradually
plugins=(
  git
  # docker  # Disabled for testing
  # kubectl # Disabled for testing
)

3. Clear completion cache:

rm ~/.zcompdump*
exec zsh

4. Check for slow commands in .zshrc:

# Add to .zshrc to profile
zmodload zsh/zprof
# ... existing config ...
# At end:
zprof

Functions Not Working

Problem: Custom functions not available

Solutions:

1. Source functions:

source ~/.config/dotfiles/functions.sh

2. Check .zshrc sources it:

grep "functions.sh" ~/.zshrc

3. Add to .zshrc if missing:

# Add this line
source ~/.config/dotfiles/functions.sh

4. Verify file exists:

ls -la ~/.config/dotfiles/functions.sh

Completions Not Working

Problem: Tab completion doesn't work

Solutions:

1. Rebuild completion cache:

rm -f ~/.zcompdump*
compinit

2. Check completion system:

# Add to ~/.zshrc if missing
autoload -Uz compinit
compinit

3. Restart shell:

exec zsh

VS Code Issues

Copilot Instructions Not Loaded

Problem: Instructions don't affect Copilot behavior

Solutions:

1. Verify file paths:

ls -la ~/.config/copilot/instructions/

2. Check settings.json:

# Ensure absolute paths with ~
code ~/.vscode/settings.json

3. Reload window:

• Cmd+Shift+P → "Reload Window"

4. Verify Copilot is enabled:

• Check GitHub Copilot status in VS Code

MCP Server Connection Failed

Problem: MCP server won't connect

Solutions:

1. Check server status:

• Cmd+Shift+P → "MCP: Show Server Status"

2. Verify environment variables:

echo $CONTEXT7_API_KEY

3. Restart VS Code:

# Quit completely
# Re-open
code .

4. Check Docker (for Docker-based servers):

docker ps
# Start Docker Desktop if not running

5. Verify mcp.json syntax:

# Validate JSON
cat ~/.vscode/mcp.json | jq .

Docker MCP Server Not Working

Problem: Kubernetes or GitKraken MCP not connecting

Solutions:

1. Ensure Docker is running:

docker ps
# If error, start Docker Desktop

2. Test Docker:

docker run hello-world

3. Check volume mounts:

# Kubernetes
ls -la ~/.kube/config

# GitKraken
ls -la ~/.gitkraken/

4. Pull images manually:

docker pull ghcr.io/stophobia/mcp-k8s:latest
docker pull gitkraken/mcp-server-gk

Git Issues

Git Configuration Not Applied

Problem: Git config not working

Solutions:

1. Check .gitconfig:

cat ~/.gitconfig

2. Verify user info:

git config --global user.name
git config --global user.email

3. Set if missing:

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

Git Credentials Not Saved

Problem: Git asks for password every time

Solutions:

1. Use SSH:

# Generate SSH key
ssh-keygen -t ed25519 -C "your@email.com"

# Add to GitHub
cat ~/.ssh/id_ed25519.pub
# Copy and add to GitHub.com → Settings → SSH Keys

2. Configure credential helper:

# macOS
git config --global credential.helper osxkeychain

# Linux
git config --global credential.helper store

Kubernetes Issues

kubectl Not Working

Problem: kubectl commands fail

Solutions:

1. Verify installation:

kubectl version --client

2. Check config:

kubectl config view

3. Test cluster connection:

kubectl cluster-info

4. Set context:

kubectl config get-contexts
kubectl config use-context <context-name>

kubectl Plugins Not Found

Problem: Installed krew plugins not available

Solutions:

1. Check PATH:

echo $PATH | grep krew

2. Add to PATH if missing:

# Add to ~/.zshrc
export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"
source ~/.zshrc

3. Verify plugin installation:

kubectl krew list

4. Reinstall plugin:

kubectl krew install <plugin>

Docker Issues

Docker Commands Require sudo (Linux)

Problem: Must use sudo for Docker

Solutions:

1. Add user to docker group:

sudo usermod -aG docker $USER

2. Log out and back in:

# Or restart shell
exec $SHELL

3. Verify:

docker ps

Docker Desktop Not Starting (macOS)

Problem: Docker Desktop won't start

Solutions:

1. Check macOS version:

• Docker Desktop requires macOS 10.15+

2. Reset Docker:

• Docker Desktop → Troubleshoot → Reset to factory defaults

3. Reinstall Docker:

brew reinstall --cask docker

Node.js / JavaScript Issues

node Command Not Found

Problem: Node.js not available

Solutions:

1. Check proto installation:

proto --version

2. Install Node:

proto install node 20
proto use node 20

3. Check PATH:

echo $PATH | grep proto

4. Add proto to PATH:

# Add to ~/.zshrc
export PATH="$HOME/.proto/bin:$PATH"
source ~/.zshrc

npm Permissions Error

Problem: npm install fails with EACCES

Solutions:

1. Use proto (recommended):

proto install node
# Proto manages permissions correctly

2. Fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Theme Issues

Prompt Not Displaying Correctly

Problem: Prompt looks broken

Solutions:

1. Install Nerd Font:

# macOS
brew tap homebrew/cask-fonts
brew install --cask font-hack-nerd-font

2. Set font in terminal:

• Terminal → Preferences → Profiles → Font → "Hack Nerd Font"

3. Check theme file:

ls ~/.oh-my-zsh/custom/themes/this-is-tobi.zsh-theme

4. Verify theme setting:

grep "ZSH_THEME" ~/.zshrc
# Should be: ZSH_THEME="this-is-tobi"

Kubernetes Context Not Showing

Problem: Kubernetes context missing from prompt

Solutions:

1. Check kube-ps1 plugin:

grep "kube-ps1" ~/.zshrc

2. Enable in .zshrc:

# Should be in plugins list
plugins=(
  ...
  kube-ps1
  ...
)

3. Verify kubectl config:

kubectl config current-context

Performance Issues

High CPU Usage

Problem: Terminal uses too much CPU

Solutions:

1. Disable unnecessary plugins:

# Edit ~/.zshrc
# Remove unused plugins

2. Disable git status in large repos:

git config --global oh-my-zsh.hide-status 1

3. Reduce history size:

# Add to ~/.zshrc
HISTSIZE=1000
SAVEHIST=1000

High Memory Usage

Problem: Shell uses too much memory

Solutions:

1. Restart shell:

exec zsh

2. Check running processes:

ps aux | grep -E "(zsh|docker|kubectl)"

3. Limit Docker resources:

• Docker Desktop → Settings → Resources → Adjust limits

Backup & Restore Issues

Backup Script Fails

Problem: Backup doesn't complete

Solutions:

1. Check destination exists:

mkdir -p ~/backups

2. Check permissions:

ls -la ~/backups

3. Check disk space:

df -h

4. Run with verbose output:

bash -x backup/backup-osx.sh -d ~/backups

Restore Doesn't Work

Problem: Files not restored correctly

Solutions:

1. Verify backup integrity:

ls -la ~/backups/dotfiles

2. Copy files manually:

cp ~/backups/dotfiles/.zshrc ~/

3. Check ownership:

sudo chown -R $USER:$USER ~/backups

4. Restore permissions:

chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/*.pub

Getting Help

Enable Debug Mode

Add to top of script to debug:

set -x  # Print commands
set -e  # Exit on error
set -u  # Error on undefined variable

Check Logs

View system logs:

# macOS
log show --predicate 'process == "zsh"' --last 1h

# Linux
journalctl -u <service> -f

Community Support

• GitHub Issues
• oh-my-zsh Wiki
• Homebrew Documentation
• VS Code Documentation

Report Issues

When reporting issues, include:

• Operating system and version
• Shell version: zsh --version
• Error messages
• Steps to reproduce
• Relevant configuration files

Prevention

Regular Maintenance

# Update packages monthly
brew update && brew upgrade  # macOS
sudo apt update && sudo apt upgrade  # Linux

# Clean caches
brew cleanup  # macOS
sudo apt autoremove  # Linux

# Backup regularly
./backup/backup-osx.sh

Version Pinning

Pin important tool versions:

# Proto
proto pin node 20
proto pin go 1.21

# Document in README
echo "Node.js: $(node --version)" >> VERSIONS.md