Troubleshooting Guide

Overview

This guide provides solutions to common issues encountered when using cpm. Issues are organized by category with symptoms, causes, and step-by-step resolution procedures.

Quick Diagnostic Commands

Run these commands to gather system information:

# Version and config
cpm --version
cpm config show

# System checks
which ssh
which rsync
which git

# Connectivity tests
cpm servers status
cpm neighbors ping <host>

# Database check
sqlite3 ~/.cpm/cpm.db "PRAGMA integrity_check;"

Installation Issues

Issue: Binary Not Found

Symptom:

$ cpm
bash: cpm: command not found

Cause: Binary not in PATH or not installed

Resolution:

  1. Check installation:

    ls -l ~/go/bin/cpm

  2. Add to PATH if needed:

    export PATH=$PATH:$HOME/go/bin
# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc

  3. Reinstall if missing:

    cd /home/alice/cpm
go install

Issue: Build Fails

Symptom:

$ go build
# cgo errors or missing dependencies

Cause: Missing build dependencies

Resolution:

  1. Install SQLite development libraries:

    # Debian/Ubuntu
sudo apt-get install libsqlite3-dev

# macOS
brew install sqlite3

# RHEL/CentOS
sudo yum install sqlite-devel

  2. Verify Go version:

    go version  # Should be 1.24.0 or later

  3. Clean and rebuild:

    go clean
go mod download
go build

Configuration Issues

Issue: Config File Not Found

Symptom:

$ cpm list
Error: config file not found

Cause: Configuration not initialized

Resolution:

# Initialize configuration
cpm config init

# Verify
cpm config show

Issue: Invalid Configuration Values

Symptom:

$ cpm push myrepo
Error: main_server not configured

Cause: Required configuration missing

Resolution:

# Check current config
cpm config show

# Set main server
cpm config set main_server git@git.example.com

# Set other required values
cpm config set data_dir ~/.cpm/data
cpm config set ssh_key_path ~/.cpm/keys/main

# Verify
cpm config show

Issue: Permission Denied on Config Directory

Symptom:

$ cpm config init
Error: permission denied: ~/.cpm

Cause: Insufficient permissions

Resolution:

# Check permissions
ls -ld ~/.cpm

# Fix ownership
sudo chown -R $USER:$USER ~/.cpm

# Fix permissions
chmod 755 ~/.cpm
chmod 600 ~/.cpm/config.yaml

SSH Connection Issues

Issue: Permission Denied (publickey)

Symptom:

$ cpm push myrepo
Error: Permission denied (publickey)

Cause: SSH key not deployed to server

Resolution:

  1. Generate key if needed:

    cpm ssh-key generate main-server

  2. Deploy key to server:

    cpm ssh-key push main-server --to git@git.example.com
# You'll need password or existing key for initial deployment

  3. Test SSH connection:

    ssh -i ~/.cpm/keys/main-server git@git.example.com

  4. Configure server to use key:

    cpm servers add origin git.example.com --key ~/.cpm/keys/main-server

Issue: Connection Timeout

Symptom:

$ cpm servers status origin
Error: connection timeout

Cause: Network issue, firewall, or wrong host/port

Resolution:

  1. Test basic connectivity:

    ping git.example.com
telnet git.example.com 22

  2. Check firewall:

    # On server
sudo ufw status
sudo iptables -L

# Ensure port 22 is open
sudo ufw allow 22/tcp

  3. Verify server configuration:

    cpm servers list
# Check host and port are correct

  4. Try alternate port:

    cpm servers remove origin
cpm servers add origin git.example.com --port 2222

Issue: Host Key Verification Failed

Symptom:

$ cpm push myrepo
Error: Host key verification failed

Cause: Server host key changed or not in known_hosts

Resolution:

  1. Remove old host key:

    ssh-keygen -R git.example.com

  2. Accept new host key:

    ssh git@git.example.com
# Type 'yes' when prompted

  3. Or disable strict checking (less secure):

    ssh -o StrictHostKeyChecking=no git@git.example.com

Repository Issues

Issue: Repository Already Exists

Symptom:

$ cpm init myrepo
Error: repository already exists at path

Cause: Repository with same name exists

Resolution:

  1. Check existing repositories:

    cpm list --local

  2. Options:

    • Use different name: cpm init myrepo-new
    • Use different path: cpm init myrepo --path /alt/path
    • Remove existing (careful!): rm -rf ~/.cpm/data/myrepo.git

Issue: Push Fails - Disk Full

Symptom:

$ cpm push myrepo
Error: No space left on device

Cause: Server disk full

Resolution:

  1. Check server disk space:

    ssh git@git.example.com df -h

  2. Free up space on server:

    # Remove old repositories
# Clean up logs
# Expand storage

  3. Use alternate server:

    cpm push myrepo --to backup-server

Issue: Repository Corruption

Symptom:

$ cpm push myrepo
Error: repository verification failed

Cause: Corrupted git repository

Resolution:

  1. Check repository integrity:

    cd ~/.cpm/data/myrepo.git
git fsck --full

  2. Attempt automatic repair:

    git fsck --full --repair

  3. If repair fails, restore from backup:

    cpm pull myrepo --from backup-server

Database Issues

Issue: Database Locked

Symptom:

$ cpm user add alice
Error: database is locked

Cause: Another cpm process or SQLite lock

Resolution:

  1. Check for running cpm processes:

    ps aux | grep cpm
kill <pid>  # if found

  2. Remove lock file if stale:

    rm ~/.cpm/cpm.db-wal
rm ~/.cpm/cpm.db-shm

  3. Check database integrity:

    sqlite3 ~/.cpm/cpm.db "PRAGMA integrity_check;"

Issue: Constraint Violation

Symptom:

$ cpm user add alice
Error: UNIQUE constraint failed: users.username

Cause: User already exists

Resolution:

  1. Check existing users:

    cpm user list

  2. Use different username or remove existing:

    cpm user remove alice
cpm user add alice --email alice@example.com

Issue: Database Corruption

Symptom:

$ cpm list
Error: database disk image is malformed

Cause: Database file corrupted

Resolution:

  1. Try to recover:

    sqlite3 ~/.cpm/cpm.db ".recover" | sqlite3 ~/.cpm/cpm-recovered.db
mv ~/.cpm/cpm.db ~/.cpm/cpm.db.backup
mv ~/.cpm/cpm-recovered.db ~/.cpm/cpm.db

  2. If recovery fails, restore from backup:

    cp ~/backups/cpm.db ~/.cpm/cpm.db

  3. If no backup, reinitialize:

    rm ~/.cpm/cpm.db
cpm config init
# Re-register repositories, users, etc.

Sync Issues

Issue: Rsync Not Found

Symptom:

$ cpm push myrepo
Error: rsync: command not found

Cause: rsync not installed

Resolution:

# Debian/Ubuntu
sudo apt-get install rsync

# macOS
brew install rsync

# RHEL/CentOS
sudo yum install rsync

# Verify
which rsync

Issue: Slow Transfer

Symptom: Transfers taking very long

Cause: Network bandwidth, large repository, no compression

Resolution:

  1. Check network:

    # Test bandwidth
iperf3 -c git.example.com

  2. Enable compression (already default):

    # Verify rsync uses -z flag
cpm push myrepo --verbose

  3. Use local network if available:

    cpm neighbors discover
cpm neighbors sync myrepo --to neighbor

  4. Reduce repository size:

    # Clean up in source repo
git gc --aggressive
git repack -a -d

Issue: Sync Verification Failed

Symptom:

$ cpm push myrepo
Warning: sync verification failed

Cause: Transfer incomplete or files differ

Resolution:

  1. Retry sync:

    cpm push myrepo --force

  2. Check for errors:

    cpm push myrepo --verbose 2>&1 | tee sync.log

  3. Verify manually:

    ssh git@git.example.com ls -la /path/to/repo.git

Neighbor Discovery Issues

Issue: No Neighbors Found

Symptom:

$ cpm neighbors discover
Discovered: 0 servers

Cause: No cpm servers on network, wrong network, firewall

Resolution:

  1. Verify network:

    ip addr show
# Check your network CIDR

  2. Specify correct network:

    cpm neighbors discover --network 192.168.1.0/24

  3. Check firewall:

    # Ensure port 9418 is open
sudo ufw allow 9418/tcp

  4. Verify cpm servers are running:

    # On potential neighbors
netstat -tuln | grep 9418

Issue: Discovery Timeout

Symptom: Discovery scan hangs or times out

Cause: Large network, slow responses

Resolution:

  1. Use smaller network range:

    cpm neighbors discover --network 192.168.1.0/26

  2. Increase timeout:

    cpm neighbors discover --timeout 5s

Performance Issues

Issue: Slow Commands

Symptom: All cpm commands slow

Cause: Database issues, disk I/O, network

Resolution:

  1. Check database size:

    ls -lh ~/.cpm/cpm.db

  2. Vacuum database:

    sqlite3 ~/.cpm/cpm.db "VACUUM;"

  3. Check disk I/O:

    iostat -x 1 5

  4. Move to faster storage:

    mv ~/.cpm /path/to/ssd/.cpm
ln -s /path/to/ssd/.cpm ~/.cpm

Organization Issues

Issue: Cannot Remove Member

Symptom:

$ cpm org remove-member myorg alice
Error: user is organization owner

Cause: Cannot remove last owner

Resolution:

  1. Add new owner first:

    cpm org add-member myorg bob --role owner

  2. Then remove:

    cpm org remove-member myorg alice

Getting Help

Enable Verbose Mode

cpm --verbose <command>

Check Logs

# System logs
journalctl -u cpm

# Application logs (if configured)
tail -f ~/.cpm/cpm.log

Collect Debug Information

# Create debug report
{
    echo "=== System Info ==="
    uname -a
    go version

    echo "=== cpm Version ==="
    cpm --version

    echo "=== Configuration ==="
    cpm config show

    echo "=== Connectivity ==="
    cpm servers status

    echo "=== Database ==="
    sqlite3 ~/.cpm/cpm.db "SELECT count(*) FROM repositories;"
} > cpm-debug.txt

Report Issues

When reporting issues, include:

  1. cpm version
  2. Operating system
  3. Full error message
  4. Steps to reproduce
  5. Configuration (sanitized)
  6. Debug information

See Also