Troubleshooting

Having issues with GitScribe? Here are solutions to common problems. If you can't find your issue here, join our Discord for help.

Installation Issues

Command not found

Problem: gitscribe: command not found after installation

Solutions:

1. Check if GitScribe is in your PATH:

   which gitscribe
   # or
   where gitscribe  # Windows

2. Add GitScribe to PATH manually:

   # Linux/macOS
   echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
   source ~/.bashrc
   
   # Windows
   setx PATH "%PATH%;C:Program FilesGitScribe"

3. Restart your terminal after installation

Permission denied

Problem: Permission errors during installation

Solutions:

# Linux/macOS - Use sudo
sudo curl -sSL https://gitscri.be/install | sudo sh

# Windows - Run as Administrator
# Right-click PowerShell → Run as Administrator

SSL/TLS errors

Problem: SSL certificate verification failed

Solutions:

# Temporary workaround (not recommended for production)
curl -sSLk https://gitscri.be/install | sh

# Better solution - Update certificates
# macOS
brew install ca-certificates

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# CentOS/RHEL
sudo yum install ca-certificates

Configuration Issues

Config file not found

Problem: GitScribe can't find configuration file

Solutions:

1. Initialize GitScribe in your repository:

   gitscribe init

2. Check config file location:

   gitscribe config list
   gitscribe doctor

3. Create config manually:

   touch .gitscribe.toml
   gitscribe config edit

Invalid configuration

Problem: Configuration parsing errors

Solutions:

# Validate configuration
gitscribe doctor

# Reset to defaults
gitscribe config reset

# Check TOML syntax
cat .gitscribe.toml | toml-validator

Git Integration Issues

No staged changes

Problem: "No staged changes found" error

Solutions:

# Stage your changes first
git add .
gitscribe generate

# Or enable auto-staging
gitscribe config set behavior.auto_stage true

Git hooks not working

Problem: GitScribe doesn't run automatically on commit

Solutions:

1. Check if hooks are installed:

   ls -la .git/hooks/prepare-commit-msg

2. Install hooks manually:

   gitscribe init --force

3. Check hook permissions:

   chmod +x .git/hooks/prepare-commit-msg

Commit message not appearing

Problem: Generated message doesn't show in editor

Solutions:

# Check editor configuration
git config --get core.editor

# Set editor explicitly
git config --global core.editor "vim"
# or
gitscribe config set editor.program vim

AI Model Issues

Local model not working

Problem: Local AI model fails to generate messages

Solutions:

1. Download model if needed:

   gitscribe model download

2. Check model path:

   gitscribe config get ai.local_model_path

3. Verify system requirements:

   gitscribe doctor --verbose

4. Fall back to rule-based:

   gitscribe config set ai.model rule-based

API key issues

Problem: "Invalid API key" or "Unauthorized" errors

Solutions:

# Check if API key is set
gitscribe config get ai.api_key

# Set API key
gitscribe config set ai.api_key "sk-..."
# or
export GITSCRIBE_API_KEY="sk-..."

# Verify API key
gitscribe status --verbose

Rate limit exceeded

Problem: "Rate limit exceeded" errors

Solutions:

• Wait for rate limit reset (shown in error)
• Upgrade to Pro for higher limits
• Use local model as fallback:

  gitscribe config set ai.fallback_model local

Performance Issues

Slow generation

Problem: Message generation takes too long

Solutions:

1. Use a faster model:

   gitscribe config set ai.model gpt-3.5-turbo

2. Reduce diff size:

   # Ignore large files
   echo "*.min.js" >> .gitscribe-ignore
   echo "package-lock.json" >> .gitscribe-ignore

3. Use local model:

   gitscribe config set ai.model local

High memory usage

Problem: GitScribe uses too much memory

Solutions:

# Use smaller local model
gitscribe config set ai.local_model_size small

# Limit context window
gitscribe config set ai.max_diff_size 5000

# Use cloud models instead
gitscribe config set ai.model gpt-3.5-turbo

Integration Issues

VS Code extension not working

Problem: GitScribe VS Code extension errors

Solutions:

1. Check GitScribe CLI is installed:

   which gitscribe

2. Reload VS Code window:

   Ctrl+Shift+P → "Developer: Reload Window"

3. Check extension logs:

   View → Output → GitScribe

TortoiseGit integration failing

Problem: Hook script not executing in TortoiseGit

Solutions:

1. Use full path to gitscribe.exe
2. Check "Wait for script to finish"
3. Enable "Show output" for debugging
4. Try batch wrapper:

   @echo off
   C:PathTogitscribe.exe generate --tortoise
   pause

Common Error Messages

"Diff too large"

# Solution 1: Commit in smaller chunks
git add -p  # Interactive staging

# Solution 2: Increase limit
gitscribe config set ai.max_diff_size 10000

# Solution 3: Exclude files
echo "large-file.bin" >> .gitscribe-ignore

"Context deadline exceeded"

# Increase timeout
gitscribe config set ai.timeout 30

# Use faster model
gitscribe config set ai.model gpt-3.5-turbo

"Invalid commit style"

# Check available styles
gitscribe config list | grep style

# Set valid style
gitscribe config set commit.style conventional

Debug Mode

Enable debug logging for detailed troubleshooting:

# Enable debug mode
export GITSCRIBE_DEBUG=true
gitscribe generate

# Verbose logging
gitscribe --verbose generate

# Write logs to file
GITSCRIBE_LOG_FILE=/tmp/gitscribe.log gitscribe generate

Recovery Options

Reset GitScribe

# Reset configuration
gitscribe config reset

# Clean cache
rm -rf ~/.gitscribe/cache

# Reinstall
gitscribe update --force

Manual uninstall

# Remove binary
sudo rm /usr/local/bin/gitscribe

# Remove config
rm -rf ~/.gitscribe
rm .gitscribe.toml

# Remove git hooks
rm .git/hooks/prepare-commit-msg

Getting Help

Diagnostic information

When reporting issues, include:

# System info
gitscribe doctor --verbose > diagnostic.txt

# Version info
gitscribe --version

# Config dump
gitscribe config list --all

# Recent logs
tail -n 100 ~/.gitscribe/logs/gitscribe.log

Support channels

• Discord Community - Real-time help
• GitHub Issues - Bug reports
• Email Support - Pro users

Pro Tip: Run gitscribe doctor --fix to automatically fix common issues!