file-transformer-s3/TROUBLESHOOTING.md

# Troubleshooting Guide

## Common Issues and Solutions

### 1. Node.js/npm not found

**Error:** `bash: npm: command not found`

**Solution:**
```bash
# On Arch Linux
sudo pacman -S nodejs npm

# On Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or run the setup script
./setup.sh
```

### 2. Python/pip not found

**Error:** `bash: pip: command not found`

**Solution:**
```bash
# On Arch Linux
sudo pacman -S python python-pip

# On Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y python3 python3-pip

# Or run the setup script
./setup.sh
```

### 3. Docker not found or permission denied

**Error:** `docker: command not found` or `Got permission denied while trying to connect to the Docker daemon`

**Solution:**
```bash
# Install Docker
# On Arch Linux
sudo pacman -S docker docker-compose

# On Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Start Docker service
sudo systemctl enable docker
sudo systemctl start docker

# Log out and back in for group changes to take effect
```

### 4. Port already in use

**Error:** `Error starting userland proxy: listen tcp 0.0.0.0:3000: bind: address already in use`

**Solution:**
```bash
# Check what's using the port
sudo lsof -i :3000

# Kill the process or change the port in .env file
# Edit .env and change REACT_APP_PORT to another value like 3001
```

### 5. Database connection failed

**Error:** `could not connect to server: Connection refused`

**Solution:**
```bash
# Check if PostgreSQL is running
docker-compose ps

# Start the services
docker-compose up -d

# Check logs
docker-compose logs postgres
```

### 6. MinIO connection failed

**Error:** `MinIO connection error`

**Solution:**
```bash
# Check if MinIO is running
docker-compose ps

# Start the services
docker-compose up -d

# Check MinIO logs
docker-compose logs minio

# Access MinIO console at http://localhost:9001
```

### 7. Build failures

**Error:** `npm ERR!` or `pip install` failures

**Solution:**
```bash
# Clear npm cache
npm cache clean --force

# Clear pip cache
pip cache purge

# Reinstall dependencies
make clean
make install-deps
```

### 8. Permission issues

**Error:** `Permission denied` when running scripts

**Solution:**
```bash
# Make scripts executable
chmod +x setup.sh
chmod +x *.sh

# Check file permissions
ls -la
```

### 9. Environment variables not loaded

**Error:** `Environment variable not found`

**Solution:**
```bash
# Check if .env file exists
ls -la .env

# Create .env from template
cp env.example .env

# Edit .env with your values
nano .env
```

### 10. React app not starting

**Error:** `Module not found` or React compilation errors

**Solution:**
```bash
# Clear node_modules and reinstall
cd dashboard
rm -rf node_modules package-lock.json
npm install

# Check for missing dependencies
npm list --depth=0
```

## Quick Fix Commands

### Reset everything and start fresh:
```bash
# Stop all services
docker-compose down -v

# Clean up
make clean

# Full setup
make setup-full

# Start services
make deploy-local
```

### Check system status:
```bash
# Check all services
make status

# Check logs
make logs

# Check dependencies
which node npm python3 docker
```

### Development mode:
```bash
# Start dashboard in dev mode
make dev-dashboard

# Start functions in dev mode
make dev-functions
```

## Getting Help

If you're still experiencing issues:

1. Check the logs: `make logs`
2. Verify your environment: `make status`
3. Check the documentation in `README.md`
4. Ensure all dependencies are installed: `./setup.sh`

## System Requirements

- **OS:** Linux (Arch, Ubuntu, Debian supported)
- **Node.js:** 16.x or higher
- **Python:** 3.8 or higher
- **Docker:** 20.x or higher
- **Docker Compose:** 2.x or higher
- **Memory:** At least 4GB RAM
- **Disk:** At least 10GB free space