Troubleshooting

Troubleshooting Guide

← FAQ | Home | Support →

---

Table of Contents

• Installation Issues
• Script Execution Problems
• Shell Completion Issues
• Git Integration Problems
• Performance Issues
• Configuration Problems
• Common Error Messages
• Debug Mode
• Getting Help

Installation Issues

Installation Script Fails

Problem: The installation script exits with an error.

Solutions:

1. Check prerequisites:

   # Verify bash version
   bash --version # Need 4.0+
   
   # Check Git
   git --version # Need 2.0+
   
   # Check curl
   curl --version

2. Manual installation:

   # Create directories
   mkdir -p ~/.local/bin ~/.config/dotrun/{bin,docs,templates}
   
   # Download dr
   curl -o ~/.local/bin/dr \
     https://raw.githubusercontent.com/jvPalma/dotrun/master/dr
   chmod +x ~/.local/bin/dr
   
   # Initialize Git
   cd ~/.config/dotrun && git init

3. Permission issues:

   # Ensure directories are writable
   chmod 755 ~/.local/bin
   chmod 755 ~/.config

Command Not Found: dr

Problem: After installation, dr command is not found.

Solutions:

1. Add to PATH:

   # Add to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish
   export PATH="$HOME/.local/bin:$PATH"
   
   # Reload shell
   source ~/.bashrc # or ~/.zshrc

2. Verify installation:

   # Check if dr exists
   ls -la ~/.local/bin/dr
   
   # Test direct execution
   ~/.local/bin/dr --version

3. Check PATH:

   echo $PATH | tr ':' '\n' | grep -E "(local/bin|\.local/bin)"

Shell Completion Not Working

Problem: Tab completion doesn't work after installation.

Solutions:

1. Bash:

   # Check if completion file exists
   ls ~/.config/dotrun/completions/drun-completion.bash
   
   # Source in ~/.bashrc
   echo 'source ~/.config/dotrun/completions/drun-completion.bash' >>~/.bashrc
   source ~/.bashrc

2. Zsh:

   # Add to fpath in ~/.zshrc
   echo 'fpath=(~/.config/dotrun/completions $fpath)' >>~/.zshrc
   echo 'autoload -U compinit && compinit' >>~/.zshrc
   source ~/.zshrc

3. Fish:

   # Copy completion file
   cp ~/.config/dotrun/completions/dr.fish \
     ~/.config/fish/completions/

Script Execution Problems

Permission Denied

Problem: Scripts fail with "Permission denied" error.

Solutions:

1. Make executable:

   chmod +x ~/.config/dotrun/bin/scriptname
   
   # Fix all scripts
   find ~/.config/dotrun/bin -type f -exec chmod +x {} \;

2. Check shebang:

   # Ensure first line is correct
   head -1 ~/.config/dotrun/bin/scriptname
   # Should be: #!/usr/bin/env bash

Script Not Found

Problem: dr scriptname returns "script not found".

Solutions:

1. Verify location:

   # List all scripts
   dr -l
   
   # Check specific script
   ls -la ~/.config/dotrun/bin/scriptname

2. Check categories:

   # If script is in category
   dr category/scriptname
   
   # List category scripts
   dr -l category/

3. Case sensitivity:

   # Scripts are case-sensitive
   dr MyScript # Different from
   dr myscript

Script Fails Silently

Problem: Script exits without output or error.

Solutions:

1. Enable debug mode:

   # Run with bash debug
   bash -x ~/.config/dotrun/bin/scriptname
   
   # Or set in script
   set -x # Enable debug
   set -e # Exit on error

2. Check exit codes:

   dr scriptname
   echo $? # Check exit code

3. Add error handling:

   #!/usr/bin/env bash
   set -euo pipefail
   trap 'echo "Error on line $LINENO"' ERR

Shell Completion Issues

Completions Not Loading

Problem: Completions don't work even after sourcing.

Solutions:

1. Check bash-completion:

   # Install bash-completion package
   # macOS
   brew install bash-completion
   
   # Ubuntu/Debian
   sudo apt install bash-completion

2. Verify completion function:

   # Check if function is loaded
   type _dr_completions

3. Manual load:

   # Force reload
   source ~/.config/dotrun/completions/drun-completion.bash
   complete -p dr # Verify

Slow Completion

Problem: Tab completion is slow.

Solutions:

1. Reduce script count:

   # Archive unused scripts
   mkdir ~/.config/dotrun/archive
   mv ~/.config/dotrun/bin/old-* ~/.config/dotrun/archive/

2. Optimize completion:

   # Use simple completion
   export DR_SIMPLE_COMPLETION=1

Git Integration Problems

Git Not Initialized

Problem: Git commands fail in DotRun directory.

Solutions:

cd ~/.config/dotrun
git init
git add .
git commit -m "Initial commit"

Merge Conflicts

Problem: Conflicts when syncing with team repository.

Solutions:

1. Resolve conflicts:

   # See conflicts
   git status
   
   # Edit conflicted files
   dr set conflicted-script
   
   # Mark resolved
   git add bin/conflicted-script
   git commit

2. Prevent conflicts:

   # Use branches
   git checkout -b personal
   
   # Keep team scripts separate
   git checkout team-scripts -- bin/team/

Performance Issues

Slow Script Listing

Problem: dr -l takes too long.

Solutions:

1. Reduce search scope:

   # List specific category
   dr -l git/
   
   # Limit depth
   export DR_MAX_DEPTH=2

2. Clean up:

   # Remove non-scripts
   find ~/.config/dotrun/bin -type f ! -executable -delete
   
   # Remove empty directories
   find ~/.config/dotrun/bin -type d -empty -delete

High Memory Usage

Problem: DotRun operations use too much memory.

Solutions:

1. Limit operations:

   # Process files in batches
   export DR_BATCH_SIZE=50

2. Clear cache:

   # If using completion cache
   rm -rf ~/.cache/dotrun/

Configuration Problems

Environment Variables Not Loading

Problem: Scripts can't access configured variables.

Solutions:

1. Check sourcing:

   # In script
   source "$DR_HOME/env"
   
   # Or
   [[ -f "$DR_HOME/env" ]] && source "$DR_HOME/env"

2. Export variables:

   # In env file
   export VAR_NAME="value" # Don't forget export!

Config File Syntax Errors

Problem: Configuration files cause errors.

Solutions:

1. Validate bash syntax:

   bash -n ~/.config/dotrun/env

2. Check YAML/JSON:

   # Validate YAML
   yamllint ~/.config/dotrun/config.yml
   
   # Validate JSON
   jq . ~/.config/dotrun/config.json

Common Error Messages

"bad interpreter"

Error: /usr/bin/env: bad interpreter: No such file or directory

Solution:

# Fix line endings (Windows issue)
dos2unix ~/.config/dotrun/bin/scriptname

# Or use sed
sed -i 's/\r$//' ~/.config/dotrun/bin/scriptname

"syntax error near unexpected token"

Error: Bash syntax error in script.

Solution:

# Check with shellcheck
shellcheck ~/.config/dotrun/bin/scriptname

# Common issues:
# - Missing quotes around variables
# - Unmatched brackets or parentheses
# - Windows line endings

"command not found" (in script)

Error: Script can't find commands.

Solution:

# Use full paths or ensure PATH
export PATH="/usr/local/bin:/usr/bin:/bin:$PATH"

# Or use command -v
if ! command -v sometool &>/dev/null; then
  echo "sometool is required"
  exit 1
fi

Debug Mode

Enable Global Debug

Set debug for all DotRun operations:

# Enable debug
export DR_DEBUG=1

# Verbose output
export DR_VERBOSE=1

# Trace execution
export DR_TRACE=1

Debug Specific Script

# Method 1: Bash debug
bash -x ~/.config/dotrun/bin/scriptname

# Method 2: In script
#!/usr/bin/env bash
[[ "${DEBUG:-}" == "1" ]] && set -x

# Method 3: Temporary
DEBUG=1 dr scriptname

Debug Output

Add debug helpers:

debug() {
  [[ "${DEBUG:-}" == "1" ]] && echo "DEBUG: $*" >&2
}

debug "Variable X = $X"
debug "Entering function Y"

Getting Help

Gather Information

When reporting issues, include:

# System info
dr --info >dr-info.txt

# Version
dr --version >>dr-info.txt

# Shell version
echo $SHELL >>dr-info.txt
$SHELL --version >>dr-info.txt

# Script list
dr -l >>dr-info.txt

# Error output
dr problematic-script 2>&1 | tee error.log

Community Support

• GitHub Issues: Report bugs
• Discussions: Ask questions
• Wiki: Read documentation

Quick Fixes Checklist

• PATH includes ~/.local/bin
• Scripts are executable (chmod +x)
• Shell completions are sourced
• Git is initialized in ~/.config/dotrun
• No syntax errors (shellcheck)
• Correct line endings (Unix, not Windows)
• Dependencies are installed
• Environment variables are exported

---

Still having issues? Open a GitHub issue with your debug information.

← FAQ | Home | Top ↑