SupascaleSupascale
Sign Up

Installation Issues

Common installation problems and solutions.

Solutions to common problems during Supascale installation.

Prerequisites Check Failed

Node.js Version Too Old

Error:

Node.js 18+ is required

Solution:

# Check current version
node --version

# Install Node.js 18+ using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

Docker Not Running

Error:

Docker is not running

Solution:

# Start Docker service
sudo systemctl start docker

# Verify Docker is running
docker ps

# Enable Docker to start on boot
sudo systemctl enable docker

Docker Compose Not Found

Error:

Docker Compose is required

Solution:

# Docker Compose V2 (recommended)
docker compose version

# If using older Docker Compose V1
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Installation Script Failures

Permission Denied

Error:

Permission denied: install.sh

Solution:

chmod +x install.sh
./install.sh

Git Clone Failed

Error:

fatal: destination path already exists

Solution:

# Remove existing directory
rm -rf supascale-web

# Or use a different install location
INSTALL_DIR=/opt/supascale ./install.sh

npm Install Failed

Error:

npm ERR! code EACCES

Solution:

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Or use nvm (recommended)
nvm use 18

Build Failed

Error:

Build failed with exit code 1

Solution:

# Check available memory
free -m

# If memory is low, add swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Retry installation
./install.sh

Database Issues

SQLite Database Locked

Error:

SQLITE_BUSY: database is locked

Solution:

# Stop all Supascale processes
pm2 stop supascale-web

# Check for other processes using the database
lsof data/supascale.db

# Kill any orphan processes
pkill -f supascale

# Restart
pm2 start supascale-web

Database Corruption

Error:

SQLITE_CORRUPT: database disk image is malformed

Solution:

# Stop application
pm2 stop supascale-web

# Backup current database
cp data/supascale.db data/supascale.db.backup

# Try to recover
sqlite3 data/supascale.db ".recover" | sqlite3 data/supascale-recovered.db

# If recovery works
mv data/supascale-recovered.db data/supascale.db

# Restart
pm2 start supascale-web

PM2 Issues

PM2 Not Found

Error:

pm2: command not found

Solution:

# Install PM2 globally
npm install -g pm2

# Verify installation
pm2 --version

Application Not Starting

Error:

PM2 process errored

Solution:

# Check PM2 logs
pm2 logs supascale-web --lines 100

# Check for port conflicts
netstat -tlnp | grep 3000

# Kill conflicting process
kill $(lsof -t -i:3000)

# Restart application
pm2 restart supascale-web

PM2 Startup Not Persisting

Problem: Application doesn't start after server reboot.

Solution:

# Generate startup script
pm2 startup

# Follow the command it outputs (run as root)
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u $USER --hp $HOME

# Save current process list
pm2 save

Environment Variable Issues

Missing NEXTAUTH_SECRET

Error:

Error: NEXTAUTH_SECRET is not set

Solution:

# Generate a secure secret
openssl rand -base64 32

# Add to .env file
echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)" >> .env

Invalid DB_ENCRYPTION_KEY

Error:

DB_ENCRYPTION_KEY must be 64 hex characters

Solution:

# Generate a valid encryption key
openssl rand -hex 32

# Add to .env file
echo "DB_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

Port Conflicts

Port 3000 Already in Use

Error:

Error: listen EADDRINUSE: address already in use :::3000

Solution:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 $(lsof -t -i:3000)

# Or change the port in .env
echo "PORT=3001" >> .env

Network Issues

Cannot Connect to Supascale

Problem: Browser shows connection refused.

Checklist:

  1. Check if application is running:

    pm2 status

  2. Check firewall rules:

    sudo ufw status
sudo ufw allow 3000

  3. Check if listening on correct interface:

    netstat -tlnp | grep 3000

  4. If using reverse proxy, check its configuration

Getting Help

If issues persist:

  1. Check logs:

    pm2 logs supascale-web --lines 200

  2. Enable debug mode:

    DEBUG=* pm2 restart supascale-web

  3. Report issues: Include log output, system info, and steps to reproduce.