Skip to main content

Troubleshooting Guide

Common Issues and Solutions​

Issue 1: "Docker is not running"​

Solution:

# Start Docker service
sudo systemctl start docker
# or on macOS: Open Docker Desktop

# Verify Docker is running
docker info

Issue 2: "Insufficient disk space"​

Solution:

# Check disk usage
df -h
du -sh postgres_data

# Clean up Docker (if safe)
docker system prune

# Free up space or move to larger disk

Issue 3: "PostgreSQL failed to start"​

Solution:

# Check container logs
docker-compose logs postgres

# Common issues:
# - Port 5432 already in use
# - Corrupted data directory
# - Permission issues

# Stop other PostgreSQL instances
sudo systemctl stop postgresql

Issue 4: "Role does not exist" errors​

Solution:

# Use the role fix mode
./upgrade_postgres_13_to_16.sh --fix-roles

# Or manually check roles
docker-compose exec postgres psql -U postgres -c "SELECT rolname FROM pg_roles WHERE rolname LIKE 'user_%';"

Issue 5: "Backup file is empty"​

Solution:

# Check PostgreSQL connectivity
docker-compose exec postgres pg_isready -U postgres

# Verify database exists
docker-compose exec postgres psql -U postgres -l

# Check .env file configuration
cat .env | grep PG_

Emergency Rollback Procedures​

If Upgrade Fails Mid-Process:

  1. Automatic Cleanup: The script automatically attempts rollback on failure

  2. Manual Rollback:

     # Stop all services
     docker-compose down

     # Restore original docker-compose.yml
     cp docker-compose.yml.bak.TIMESTAMP docker-compose.yml

     # Restore original data directory
     rm -rf postgres_data
     mv postgres_data_old_pg13_TIMESTAMP postgres_data

     # Start services
     docker-compose up -d

     # Verify restoration
     docker-compose exec postgres psql -U postgres -c "SELECT version();"

  3. Restore from Volume Backup:

    # If data directory is corrupted
    rm -rf postgres_data
    cp -r backups/postgres_data_backup_TIMESTAMP postgres_data

    # Start services
    docker-compose up -d