TROUBLESHOOTING.md

🔧 Troubleshooting Guide

This guide helps you diagnose and fix common issues with Cascade CLI.

🚨 Quick Diagnostic

Before diving into specific issues, run the built-in diagnostics:

# Run comprehensive health check
ca doctor

# Get detailed system information
ca doctor --verbose

# Show configuration
ca config list

# Check Git status
git status

---

📋 Common Issues

🔴 Installation & Setup

"command not found: cc"

Symptoms:

$ ca --version
bash: cc: command not found

Solutions:

1. Check if binary exists:

   # If installed via cargo
   ls ~/.cargo/bin/cc
   
   # If built from source
   ls target/release/cc

2. Fix PATH:

   # Add to PATH temporarily
   export PATH="$HOME/.cargo/bin:$PATH"
   
   # Make permanent (bash)
   echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   
   # Make permanent (zsh)
   echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

3. Reinstall:

   # Via cargo
   cargo install --path . --force
   
   # Or rebuild
   cargo build --release
   cp target/release/ca ~/.local/bin/

Rust compilation errors

Symptoms:

error: linking with `ca` failed: exit status: 1

Solutions:

1. Update Rust:

   rustup update
   rustc --version  # Should be 1.82+

2. Install system dependencies:

   # Ubuntu/Debian
   sudo apt update
   sudo apt install build-essential pkg-config libssl-dev
   
   # macOS
   xcode-select --install
   
   # CentOS/RHEL
   sudo yum groupinstall "Development Tools"
   sudo yum install openssl-devel

3. Clear cache and rebuild:

   cargo clean
   cargo build --release

Permission denied errors

Symptoms:

$ ca --version
Permission denied

Solutions:

1. Fix permissions:

   chmod +x ~/.cargo/bin/cc

2. Install to user directory:

   cargo install --path . --root ~/.local
   export PATH="$HOME/.local/bin:$PATH"

🔴 Configuration Issues

"Repository not initialized"

Symptoms:

Error: Repository is not initialized for Cascade CLI

Solutions:

1. Check if in Git repository:

   git status
   # Should show repository status, not "not a git repository"

2. Initialize Cascade CLI:

   ca init --bitbucket-url https://your-bitbucket.com
   # Or use setup wizard
   ca setup

3. Fix corrupted configuration:

   rm -rf .cascade/
   ca init --force

Bitbucket connection failures

Symptoms:

Error: Failed to connect to Bitbucket: HTTP 401 Unauthorized
Error: Failed to connect to Bitbucket: Connection timeout

Solutions:

1. Verify credentials:

   ca config get bitbucket.token
   ca config get bitbucket.url
   
   # Test manually
   curl -H "Authorization: Bearer YOUR_TOKEN" \
        "https://your-bitbucket.com/rest/api/1.0/projects"

2. Check Personal Access Token:

   • Token must have Repository Write permissions
   • Token must not be expired
   • Check Bitbucket → Settings → Personal Access Tokens

3. Network issues:

   # Check DNS resolution
   nslookup your-bitbucket.com
   
   # Test connectivity
   ping your-bitbucket.com
   
   # Check proxy settings
   echo $HTTP_PROXY
   echo $HTTPS_PROXY

4. Corporate firewall/proxy:

   # Configure Git for proxy
   git config --global http.proxy http://proxy.company.com:8080
   git config --global https.proxy https://proxy.company.com:8080
   
   # Set environment variables
   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=https://proxy.company.com:8080

Invalid project/repository settings

Symptoms:

Error: Project 'INVALID' not found
Error: Repository 'invalid-repo' not found in project 'PROJECT'

Solutions:

1. List available projects:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
        "https://your-bitbucket.com/rest/api/1.0/projects" | jq '.values[].key'

2. List repositories in project:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
        "https://your-bitbucket.com/rest/api/1.0/projects/PROJECT/repos" | jq '.values[].name'

3. Auto-detect from Git remote:

   git remote -v
   # Use the setup wizard to auto-detect
   ca setup --force

🔴 Stack Management Issues

"No active stack" errors

Symptoms:

Error: No active stack found

Solutions:

1. Check existing stacks:

   ca stacks list

2. Create or activate a stack:

   # Create new stack
   ca stacks create my-feature --base main
   
   # Or activate existing stack
   ca stacks switch existing-stack-name

3. Recover from corruption:

   # Check stack metadata
   ls .cascade/stacks/
   
   # Validate stack integrity
   ca stacks validate
   
   # Force create new stack if needed
   ca stacks create recovery-stack --base main --force

Stack synchronization failures

Symptoms:

Error: Failed to sync stack: merge conflicts detected
Error: Base branch 'main' not found

Solutions:

1. Resolve merge conflicts:

   # Check conflict status
   git status
   
   # Resolve conflicts manually
   git add .
   ca rebase continue
   
   # Or abort and try different strategy
   ca rebase abort
   ca stacks sync --strategy merge

2. Update base branch:

   # Fetch latest changes
   git fetch origin
   
   # Ensure base branch exists
   git branch -r | grep origin/main
   
   # Update local base
   git checkout main
   git pull origin main
   
   # Try sync again
   ca stacks sync

3. Stack corruption recovery:

   # Backup current work
   git stash
   
   # Reset stack to known good state
   ca stack  # Note commit hashes
   git checkout main
   git pull origin main
   
   # Recreate stack manually
   ca stacks create recovery --base main
   git cherry-pick COMMIT_HASH_1
   ca stacks push
   git cherry-pick COMMIT_HASH_2
   ca stacks push

Pull request creation failures

Symptoms:

Error: Failed to create pull request: title cannot be empty
Error: Failed to create pull request: source branch not found

Solutions:

1. Check commit exists:

   git log --oneline -n 5
   ca stack

2. Verify branch state:

   # Check current branch
   git branch
   
   # Ensure commits are pushed to remote
   git push origin current-branch

3. Manual PR creation:

   # Get commit details
   ca stack
   
   # Create PR manually in Bitbucket UI
   # Then update stack metadata
   ca stacks submit --pr-id 123

🔴 Performance Issues

Slow operations in large repositories

Symptoms:

• Commands taking > 30 seconds
• High memory usage
• Timeouts

Solutions:

1. Optimize Git configuration:

   git config core.preloadindex true
   git config core.fscache true
   git config gc.auto 256

2. Adjust Cascade CLI settings:

   ca config set performance.cache_size 500
   ca config set performance.parallel_operations false
   ca config set network.timeout 120

3. Repository maintenance:

   # Clean up Git repository
   git gc --aggressive
   git prune
   
   # Clear Cascade cache
   rm -rf .cascade/cache/

High memory usage

Solutions:

1. Reduce cache size:

   ca config set performance.cache_size 100

2. Monitor memory usage:

   # During operation
   top -p $(pgrep cc)
   
   # Check cache directory size
   du -sh .cascade/cache/

🔴 TUI (Terminal User Interface) Issues

TUI display problems

Symptoms:

• Garbled characters
• No colors
• Layout issues

Solutions:

1. Check terminal capabilities:

   echo $TERM
   # Should be xterm-256color or similar
   
   # Test colors
   tput colors
   # Should be 256 or higher

2. Fix terminal settings:

   export TERM=xterm-256color
   
   # For tmux users
   export TERM=screen-256color

3. Disable colors if needed:

   ca config set ui.colors false
   ca tui

TUI crashes or freezes

Solutions:

1. Update terminal:

   # Check for terminal updates
   # Try different terminal: iTerm2, Alacritty, etc.

2. Reset TUI settings:

   ca config unset ui.tui_refresh_rate
   ca config unset ui.tui_theme

3. Use alternative interface:

   # Use CLI instead of TUI
   ca stacks list --verbose
   ca viz stack

🔴 Git Hooks Issues

Hooks not working

Symptoms:

• Commits not auto-added to stack
• No pre-push validation

Solutions:

1. Check hook installation:

   ca hooks status
   ls -la .git/hooks/

2. Verify permissions:

   chmod +x .git/hooks/post-commit
   chmod +x .git/hooks/pre-push

3. Reinstall hooks:

   ca hooks uninstall
   ca hooks install --force

Hook conflicts

Symptoms:

Error: Existing hook found, use --force to overwrite

Solutions:

1. Backup existing hooks:

   cp .git/hooks/post-commit .git/hooks/post-commit.backup

2. Force install:

   ca hooks install --force

3. Manual integration:

   # Edit existing hook to call Cascade CLI
   echo "ca stacks push --auto || true" >> .git/hooks/post-commit

---

🔍 Advanced Debugging

Enable Debug Logging

# Set debug level
export CASCADE_LOG_LEVEL=debug

# Run command with debug output
ca stacks push

# Check logs
tail -f ~/.cascade/logs/cascade.log

Capture System Information

# Full diagnostic report
ca doctor --verbose > cascade-debug.txt

# Add system info
echo "=== System Info ===" >> cascade-debug.txt
uname -a >> cascade-debug.txt
git --version >> cascade-debug.txt
rustc --version >> cascade-debug.txt

# Add configuration
echo "=== Configuration ===" >> cascade-debug.txt
ca config list >> cascade-debug.txt

# Add recent logs
echo "=== Recent Logs ===" >> cascade-debug.txt
tail -50 ~/.cascade/logs/cascade.log >> cascade-debug.txt

Network Debugging

# Test Bitbucket API manually
curl -v -H "Authorization: Bearer YOUR_TOKEN" \
     "https://your-bitbucket.com/rest/api/1.0/projects"

# Check DNS resolution
dig your-bitbucket.com

# Test with different timeout
ca config set network.timeout 300

Repository State Analysis

# Check Git integrity
git fsck --full

# Analyze repository size
git count-objects -vH

# Check remote configuration
git remote show origin

# Analyze stack metadata
find .cascade/ -name "*.json" -exec cat {} \;

---

🛠️ Recovery Procedures

Complete Reset

If everything is broken:

# 1. Backup important work
git stash
git branch backup-$(date +%Y%m%d)

# 2. Remove Cascade configuration
rm -rf .cascade/

# 3. Reinitialize
ca setup

# 4. Recreate stacks manually
ca stacks create recovery --base main
# Cherry-pick commits as needed

Stack Recovery

For corrupted stack metadata:

# 1. Export stack information
ca stack > stack-backup.txt

# 2. Note commit hashes and PR IDs

# 3. Delete corrupted stack
ca stacks delete problematic-stack --force

# 4. Recreate with same commits
ca stacks create recovered-stack --base main
git cherry-pick HASH1
ca stacks push
git cherry-pick HASH2  
ca stacks push

# 5. Reconnect to existing PRs
ca config set stack.recovered-stack.pr.1 PR_ID_1
ca config set stack.recovered-stack.pr.2 PR_ID_2

Configuration Recovery

For broken configuration:

# 1. Backup current config
cp .cascade/config.toml .cascade/config.toml.backup

# 2. Reset to defaults
ca config reset

# 3. Reconfigure step by step
ca config set bitbucket.url "https://your-bitbucket.com"
ca config set bitbucket.project "PROJECT"
ca config set bitbucket.repository "repo"
ca config set bitbucket.token "YOUR_TOKEN"

# 4. Test configuration
ca doctor

---

📞 Getting Help

Self-Service Resources

1. Built-in help:

   ca --help
   ca stack --help
   ca stacks create --help

2. Diagnostics:

   ca doctor --verbose

3. Documentation:

   • User Manual - Complete command reference
   • Installation Guide - Setup instructions
   • Configuration Guide - Settings reference

Community Support

1. Search existing issues:

   • GitHub Issues
   • Use search terms: error message, symptom keywords

2. Community discussions:

   • GitHub Discussions
   • Stack Overflow (tag: cascade-cli)

3. Create new issue: Include this information:

   # System information
   ca doctor --verbose
   
   # Error reproduction steps
   # Expected vs actual behavior
   # Configuration (sanitized)
   ca config list | sed 's/token = .*/token = [REDACTED]/'

Enterprise Support

For enterprise users:

1. Internal support channels:

   • Check your company's internal documentation
   • Contact IT support for network/proxy issues

2. Configuration templates:

   • Ask your team lead for standard configuration
   • Check if there's a company-specific setup guide

---

🎯 Prevention Tips

Best Practices

1. Regular maintenance:

   # Weekly repository cleanup
   git gc
   ca doctor
   
   # Monthly cache cleanup
   rm -rf .cascade/cache/

2. Configuration backup:

   # Backup configuration
   cp .cascade/config.toml ~/.cascade-config-backup.toml
   
   # Version control team config
   git add .cascade/config.toml
   git commit -m "Add team Cascade CLI configuration"

3. Monitor health:

   # Regular health checks
   ca doctor | grep -E "(ERROR|WARN)"
   
   # Check for updates
   cargo install cascade-cli --force

Common Mistakes to Avoid

1. Don't manually force push to shared branches (Cascade CLI handles force pushes safely during rebase)
2. Don't ignore merge conflicts
3. Don't work on multiple stacks simultaneously without switching
4. Don't delete .cascade/ directory unless troubleshooting
5. Don't commit sensitive information in configuration

---

⚡ Smart Force Push Issues

Force Push Failed

If force push operations fail during rebase:

# Error: Force push rejected
# Solution 1: Check branch protection rules
git ls-remote --heads origin | grep your-branch

# Solution 2: Verify you have push permissions
git remote show origin

# Solution 3: Force push manually as fallback
git checkout original-branch
git reset --hard versioned-branch
git push --force-with-lease origin original-branch

PR Links Broken After Rebase

If PRs don't update correctly:

# Check if PRs still exist
ca stacks prs --verbose

# Manually update PR if needed  
ca config set stack.STACK_NAME.pr.INDEX PR_ID

# Re-submit if PR was closed
ca stacks submit INDEX --title "Updated after rebase"

Temporary Branches Accumulating

If a rebase operation is interrupted, temporary branches may be left behind:

# Check for orphaned temp branches (dry-run)
ca cleanup

# Actually delete them
ca cleanup --execute

# Force delete even if they have unmerged commits
ca cleanup --execute --force

# Or manually list and delete
git branch | grep -E '.*-temp-[0-9]+$'
git branch -D branch-temp-1234567890

Why this happens: During rebase, Cascade creates temporary branches with timestamps (e.g., feature-temp-1234567890). These are normally cleaned up automatically, but may remain if the process is killed or errors occur.

Force Push Safety Concerns

Understanding when force pushes are safe:

# Cascade CLI force pushes are safe because:
# 1. Only affects your feature branches (never main/develop)
# 2. Validates existing PRs before pushing
# 3. Creates backup branches before operations
# 4. Uses --force-with-lease for additional safety

# Check backup branches exist
git branch | grep -E '.*-v[0-9]+$'

# Manually verify safety
git log --oneline origin/your-branch..your-branch-v2

---

📊 Error Code Reference

Code	Meaning	Common Solutions
E001	Configuration missing	Run ca init or ca setup
E002	Git repository not found	Ensure you're in a Git repository
E003	Bitbucket connection failed	Check credentials and network
E004	Stack not found	Use ca stacks list to see available stacks
E005	Merge conflict detected	Resolve conflicts and run ca rebase continue or ca sync continue
E006	Invalid commit hash	Check commit exists with git log
E007	Permission denied	Check file permissions and access rights
E008	Network timeout	Increase timeout with ca config set network.timeout 120

---

If your issue isn't covered here, please create an issue with detailed information about your problem.