file-transformer-s3/TROUBLESHOOTING.md

Troubleshooting Guide

Common Issues and Solutions

1. Node.js/npm not found

Error: bash: npm: command not found

Solution:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# Stop all services
docker-compose down -v

# Clean up
make clean

# Full setup
make setup-full

# Start services
make deploy-local

Check system status:

# Check all services
make status

# Check logs
make logs

# Check dependencies
which node npm python3 docker

Development mode:

# 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