ToolJet/docs/versioned_docs/version-3.16.0-LTS/setup/postgresql-13-16/tj/troubleshooting.md

id	title
troubleshooting	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