Troubleshooting Guide

Common issues and solutions for DotClaude setup and usage.

Installation Issues

Command Not Found After Installation

Symptoms:

bash

$ ll2
command not found: ll2

$ cat2 README.md
command not found: cat2

Solutions:

Reload your shell:

bash

# Option 1: Reload current shell
exec $SHELL

# Option 2: Source configurations
source ~/.zshrc
source ~/.aliases

Check PATH configuration:

bash

# Verify modern tools are in PATH
echo $PATH | tr ':' '\n' | grep -E "(local|cargo|homebrew)"

# Should see entries like:
# /Users/username/.local/bin
# /Users/username/.cargo/bin
# /opt/homebrew/bin

Re-apply configurations:

bash

# Apply aliases package
./scripts/stow-package.sh aliases

# Apply environment package
./scripts/stow-package.sh environment

# Reload shell
exec $SHELL

Homebrew Installation Failures

Symptoms:

bash

$ ./scripts/setup-tools.sh
Error: No available formula with name "exa"

Solutions:

Update Homebrew:

bash

brew update
brew upgrade

Check alternative formulas:

bash

# exa was replaced by eza
brew install eza

# Check what's available
brew search bat
brew search fd

Manual installation:

bash

# Install core tools manually
brew install eza bat fd ripgrep git-delta difftastic zoxide dust procs bottom

Stow Package Issues

Stow Conflicts

Symptoms:

bash

$ ./scripts/stow-package.sh git
WARNING! stowing git would cause conflicts:
  * cannot stow .gitconfig over existing target

Solutions:

Check what conflicts exist:

bash

./scripts/stow-package.sh git status

Backup and remove conflicting files:

bash

# Backup first
./scripts/backup.sh git

# Remove existing config (it's backed up)
rm ~/.gitconfig

# Apply package
./scripts/stow-package.sh git

Use the adopt flag (advanced):

bash

# This moves existing files into the stow package
stow --adopt -v -d ~/.dotfiles/stow -t ~ git

GNU Stow Not Available

Symptoms:

bash

$ ./scripts/test-config.sh stow
[ERROR] GNU Stow is not installed

Solutions:

Install GNU Stow:

bash

# macOS with Homebrew
brew install stow

# Verify installation
which stow
stow --version

Update PATH if needed:

bash

# Add Homebrew to PATH
export PATH="/opt/homebrew/bin:$PATH"

# Or for Intel Macs
export PATH="/usr/local/bin:$PATH"

Git Configuration Issues

Git Log Format Problems

Symptoms:

bash

$ git lg
fatal: bad config line 104 in file .gitconfig

Solutions:

Test git config syntax:

bash

git config --list | head -10

Restore from backup:

bash

./scripts/restore.sh latest git

Check specific config sections:

bash

# Test alias section
git config --get-regexp "alias.*"

# Test user section  
git config --get-regexp "user.*"

Delta/Difftastic Not Working

Symptoms:

bash

$ git diff
fatal: cannot run delta: No such file or directory

Solutions:

Install missing tools:

bash

brew install git-delta difftastic

Check git config:

bash

git config --get core.pager
git config --get interactive.diffFilter

Temporary disable:

bash

# Use without delta temporarily
git -c core.pager=less diff

GPG Signing Issues

Symptoms:

bash

$ git commit -m "test"
error: gpg failed to sign the data

Solutions:

Check GPG configuration:

bash

git config --get user.signingkey
git config --get commit.gpgsign
git config --get gpg.format

Test SSH key signing:

bash

# Test SSH key signing
ssh-add -L

Temporary disable signing:

bash

git -c commit.gpgsign=false commit -m "test message"

Tmux Issues

Keybinding Problems

Symptoms:

Tmux keybindings not working as expected
C-a prefix not responding
Vim-style navigation not working

Solutions:

Reload tmux configuration:

bash

# From within tmux
C-a r    # Reload config (if working)

# Or manually
tmux source-file ~/.tmux.conf

Check tmux version:

bash

tmux -V
# Needs tmux 3.0+ for some features

Test configuration syntax:

bash

tmux -f ~/.tmux.conf -C "list-keys" | head -5

Kill and restart tmux:

bash

tmux kill-server
tmux

Claude Code Workspace Issues

Symptoms:

bash

$ cw myproject
command not found: cw

Solutions:

Check script availability:

bash

which tmux-claude-workspace
ls -la scripts/tmux-claude-workspace

Make script executable:

bash

chmod +x scripts/tmux-claude-workspace

Add to PATH:

bash

# Check if ~/.local/bin is in PATH
echo $PATH | grep "\.local/bin"

# Add if missing
export PATH="$HOME/.local/bin:$PATH"

Use full path:

bash

./scripts/tmux-claude-workspace myproject feature1 feature2

Git Worktree Conflicts

Symptoms:

bash

fatal: 'feature-auth' is already checked out at '.worktrees/feature-auth'

Solutions:

List existing worktrees:

bash

git worktree list

Remove conflicting worktree:

bash

git worktree remove .worktrees/feature-auth

Prune stale worktrees:

bash

git worktree prune

Shell Configuration Issues

Zsh vs Bash Compatibility

Symptoms:

Aliases not working in different shells
Path issues between shells

Solutions:

Check current shell:

bash

echo $SHELL
ps -p $$

Ensure proper configuration loading:

bash

# For zsh users
source ~/.zshrc

# For bash users  
source ~/.bashrc

Check configuration file existence:

bash

ls -la ~/.zshrc ~/.bashrc ~/.bash_profile

Environment Variable Issues

Symptoms:

bash

$ echo $EDITOR
# Empty or wrong value

Solutions:

Check environment package:

bash

./scripts/test-config.sh environment

Source environment manually:

bash

source ~/.zshenv

Verify PATH additions:

bash

echo $PATH | tr ':' '\n' | grep -v "^/usr\|^/bin"

Performance Issues

Slow Command Response

Symptoms:

Modern commands (ll2, cat2, etc.) are slower than expected
Shell startup is slow

Solutions:

Check for alias loops:

bash

alias | grep -E "(ll2|cat2|find2)"

Test tools directly:

bash

# Test without aliases
/opt/homebrew/bin/eza -la
/opt/homebrew/bin/bat README.md

Profile shell startup:

bash

# For zsh
time zsh -i -c exit

# Check what's loading
zsh -x -i -c exit 2>&1 | head -20

Large Repository Performance

Symptoms:

find2/fd is slow on large codebases
git operations taking too long

Solutions:

Use tool-specific configurations:

bash

# fd: exclude directories
find2 --exclude node_modules --exclude .git

# ripgrep: use .rgignore files
echo "node_modules/" >> .rgignore

Check .gitignore coverage:

bash

# Tools respect .gitignore by default
cat .gitignore | grep -E "(node_modules|target|build)"

Recovery Procedures

Complete System Recovery

When everything is broken:

Emergency shell with original configs:

bash

# Start new terminal
# Don't source any custom configs
bash --noprofile --norc

Restore everything:

bash

cd ~/.dotfiles
./scripts/restore.sh latest all

Remove all stow packages:

bash

for pkg in git tmux aliases environment; do
    ./scripts/stow-package.sh $pkg remove 2>/dev/null || true
done

Start fresh:

bash

exec $SHELL
# Should be back to original state

Selective Recovery

When specific component is broken:

Identify the problem:

bash

./scripts/test-config.sh all

Restore specific component:

bash

./scripts/restore.sh latest COMPONENT

Re-test and re-apply if needed:

bash

./scripts/test-config.sh COMPONENT
./scripts/stow-package.sh COMPONENT

Getting Help

Debug Information Collection

Before asking for help, collect:

System information:

bash

uname -a
echo $SHELL
which stow git tmux

Configuration status:

bash

./scripts/test-config.sh all
ls -la stow/*/

Recent backups:

bash

ls -la backups/

Log Files and Error Messages

Important locations:

Backup manifests: backups/*/MANIFEST
Stow operations: Use -v flag for verbose output
Shell startup issues: Use zsh -x for debugging

Common Solutions Summary

Issue	Quick Fix
Command not found	`exec $SHELL`
Stow conflicts	`./scripts/backup.sh && rm conflicting-file`
Git config errors	`./scripts/restore.sh latest git`
Tmux not working	`tmux kill-server && tmux`
Slow performance	Check for alias loops, exclude large dirs
Complete failure	`./scripts/restore.sh latest all`

Most issues can be resolved by reloading configurations or restoring from the automatic backups. The safety system is designed to make recovery straightforward and reliable.

Prevention

Best practices to avoid issues:

Always test configurations before applying
Keep regular backups (automatic system handles this)
Apply changes incrementally, one package at a time
Keep existing terminal sessions open when testing
Read error messages carefully - they usually indicate the exact problem

For additional help, check the command reference or review the safety guide.

Troubleshooting Guide ​

Installation Issues ​

Command Not Found After Installation ​

Homebrew Installation Failures ​

Stow Package Issues ​

Stow Conflicts ​

GNU Stow Not Available ​

Git Configuration Issues ​

Git Log Format Problems ​

Delta/Difftastic Not Working ​

GPG Signing Issues ​

Tmux Issues ​

Keybinding Problems ​

Claude Code Workspace Issues ​

Git Worktree Conflicts ​

Shell Configuration Issues ​

Zsh vs Bash Compatibility ​

Environment Variable Issues ​

Performance Issues ​

Slow Command Response ​

Large Repository Performance ​

Recovery Procedures ​

Complete System Recovery ​

Selective Recovery ​

Getting Help ​

Debug Information Collection ​

Log Files and Error Messages ​

Common Solutions Summary ​

Prevention ​

Troubleshooting Guide

Installation Issues

Command Not Found After Installation

Homebrew Installation Failures

Stow Package Issues

Stow Conflicts

GNU Stow Not Available

Git Configuration Issues

Git Log Format Problems

Delta/Difftastic Not Working

GPG Signing Issues

Tmux Issues

Keybinding Problems

Claude Code Workspace Issues

Git Worktree Conflicts

Shell Configuration Issues

Zsh vs Bash Compatibility

Environment Variable Issues

Performance Issues

Slow Command Response

Large Repository Performance

Recovery Procedures

Complete System Recovery

Selective Recovery

Getting Help

Debug Information Collection

Log Files and Error Messages

Common Solutions Summary

Prevention