Skip to main content

​
Deployment Issues

This guide helps you diagnose and resolve common issues encountered during Clipron AI deployment. Issues are organized by category with step-by-step solutions.

​
Service Startup Issues

​
Backend Service Won’t Start

Error: Address already in use: 8000Diagnosis:
# Check what's using port 8000
sudo lsof -i :8000
sudo netstat -tulpn | grep :8000
Solutions:
# Option 1: Kill the conflicting process
sudo kill -9 <PID>

# Option 2: Change the port in configuration
# Edit backend/.env
PORT=8001

# Option 3: Use a different port temporarily
cd backend
source venv/bin/activate
uvicorn main:app --port 8001
Error: No module named 'fastapi' or similar import errorsDiagnosis:
# Check if virtual environment is activated
which python
pip list | grep fastapi

# Check virtual environment path
echo $VIRTUAL_ENV
Solutions:
# Recreate virtual environment
cd backend
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Or use the installation script
./install_ai_dependencies.sh
Error: could not connect to server or database does not existDiagnosis:
# Test database connection
cd backend
source venv/bin/activate
python -c "from database import engine; engine.connect(); print('Database OK')"

# Check PostgreSQL status (if using PostgreSQL)
sudo systemctl status postgresql
Solutions:
# For PostgreSQL issues
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Recreate database
sudo -u postgres createdb clipron_db

# For SQLite issues (development)
rm backend/clipron.db
python backend/init_db.py

# Check DATABASE_URL in .env file
cat backend/.env | grep DATABASE_URL

​
Frontend Build Issues

Error: error @rollup/[email protected]: The platform "linux" is incompatibleDiagnosis:
node --version
npm --version
Solutions:
# Install Node.js 18 LTS
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clear npm cache and reinstall
cd frontend
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
Error: JavaScript heap out of memorySolutions:
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

# Or modify package.json
"scripts": {
  "build": "NODE_OPTIONS='--max-old-space-size=4096' react-scripts build"
}

# For servers with limited RAM, use swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
Error: Frontend can’t connect to backend APIDiagnosis:
# Check frontend environment variables
cat frontend/.env.production

# Test API connectivity
curl -I https://yourdomain.com/api/health
Solutions:
# Ensure correct API URL in frontend/.env.production
REACT_APP_API_URL=https://yourdomain.com/api

# Rebuild frontend after environment changes
cd frontend
npm run build

# Check Nginx configuration for API proxy
sudo nginx -t
sudo systemctl reload nginx

​
Network and SSL Issues

​
SSL Certificate Problems

Error: Failed to obtain certificate or Challenge failedDiagnosis:
# Check domain DNS resolution
nslookup yourdomain.com
dig yourdomain.com

# Test HTTP accessibility
curl -I http://yourdomain.com
Solutions:
# Ensure domain points to server IP
# Check DNS settings with your domain provider

# Stop nginx temporarily for standalone mode
sudo systemctl stop nginx
sudo certbot certonly --standalone -d yourdomain.com

# Or use webroot mode
sudo certbot certonly --webroot -w /var/www/html -d yourdomain.com

# Restart nginx
sudo systemctl start nginx
Error: Browser blocks HTTP requests from HTTPS siteSolutions:
# Ensure all API calls use HTTPS
# Check frontend/.env.production
REACT_APP_API_URL=https://yourdomain.com/api

# Add security headers to Nginx
add_header Content-Security-Policy "upgrade-insecure-requests";
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";

# Reload Nginx
sudo systemctl reload nginx

​
Firewall and Network Issues

Error: Connection refused when accessing the siteDiagnosis:
# Check if services are running
sudo systemctl status nginx
sudo systemctl status clipron

# Check listening ports
sudo netstat -tulpn | grep -E ':80|:443|:8000'

# Test local connectivity
curl -I http://localhost
curl -I http://localhost:8000/health
Solutions:
# Start services if not running
sudo systemctl start nginx
sudo systemctl start clipron

# Check firewall settings
sudo ufw status
sudo ufw allow 80
sudo ufw allow 443
sudo ufw allow 22

# For cloud providers, check security groups
# AWS: Security Groups
# GCP: Firewall Rules
# Azure: Network Security Groups
Error: Nginx returns 502 Bad GatewayDiagnosis:
# Check backend service status
sudo systemctl status clipron
sudo journalctl -u clipron -n 50

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

# Test backend directly
curl -I http://localhost:8000/health
Solutions:
# Restart backend service
sudo systemctl restart clipron

# Check Nginx proxy configuration
sudo nginx -t

# Verify proxy_pass URL in Nginx config
# Should be: proxy_pass http://localhost:8000/;

# Check SELinux (if enabled)
sudo setsebool -P httpd_can_network_connect 1

​
Database Issues

​
PostgreSQL Problems

Error: FATAL: password authentication failed for user "clipron"Solutions:
# Reset PostgreSQL password
sudo -u postgres psql
ALTER USER clipron PASSWORD 'new_password';
\q

# Update DATABASE_URL in .env
DATABASE_URL=postgresql://clipron:new_password@localhost/clipron_db

# Check pg_hba.conf authentication method
sudo nano /etc/postgresql/13/main/pg_hba.conf
# Ensure line exists: local clipron_db clipron md5

# Restart PostgreSQL
sudo systemctl restart postgresql
Error: FATAL: database "clipron_db" does not existSolutions:
# Create database
sudo -u postgres createdb clipron_db
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE clipron_db TO clipron;"

# Initialize database schema
cd backend
source venv/bin/activate
python init_db.py

# Or run migrations
alembic upgrade head
Error: QueuePool limit of size 20 overflow 30 reachedSolutions:
# Increase connection pool size in backend/.env
DB_POOL_SIZE=50
DB_MAX_OVERFLOW=100

# Or in database configuration
# Edit backend/database.py
engine = create_engine(
    DATABASE_URL,
    pool_size=50,
    max_overflow=100,
    pool_timeout=30
)

# Restart backend service
sudo systemctl restart clipron

​
SQLite Issues (Development)

Error: database is lockedSolutions:
# Stop all processes using the database
sudo systemctl stop clipron
pkill -f "python main.py"

# Remove lock file if it exists
rm backend/clipron.db-wal
rm backend/clipron.db-shm

# Restart service
sudo systemctl start clipron

# If problem persists, recreate database
rm backend/clipron.db
python backend/init_db.py

​
Permission and File System Issues

​
File Permission Problems

Error: Permission denied when accessing filesSolutions:
# Fix ownership of application files
sudo chown -R clipron:clipron /opt/clipron/

# Fix permissions
sudo chmod -R 755 /opt/clipron/
sudo chmod 644 /opt/clipron/backend/.env

# Fix log directory permissions
sudo mkdir -p /var/log/clipron
sudo chown clipron:clipron /var/log/clipron
sudo chmod 755 /var/log/clipron

# Fix systemd service file permissions
sudo chmod 644 /etc/systemd/system/clipron.service
sudo systemctl daemon-reload
Error: No space left on deviceDiagnosis:
# Check disk usage
df -h
du -sh /opt/clipron/
du -sh /var/log/

# Find large files
find /opt/clipron/ -type f -size +100M
Solutions:
# Clean up logs
sudo journalctl --vacuum-time=7d
sudo find /var/log/ -name "*.log" -mtime +30 -delete

# Clean up old analysis results
cd /opt/clipron/backend
python -c "
from database import SessionLocal
from models import Analysis
from datetime import datetime, timedelta

db = SessionLocal()
old_date = datetime.utcnow() - timedelta(days=90)
db.query(Analysis).filter(Analysis.created_at < old_date).delete()
db.commit()
"

# Clean up temporary files
sudo rm -rf /tmp/clipron_*
sudo rm -rf /opt/clipron/backend/uploads/temp/

​
API and External Service Issues

​
AI API Connection Problems

Error: 401 Unauthorized from AI APIsSolutions:
# Verify API keys in .env file
cat backend/.env | grep -E "(GOOGLE_GEMINI|DEEPSEEK|ANTHROPIC|OPENAI)_API_KEY"

# Test API keys manually
cd backend
source venv/bin/activate
python quick_ai_test.py

# Check API key format and validity
# Google Gemini: Should start with "AI"
# DeepSeek: Should be a long alphanumeric string
# Anthropic: Should start with "sk-ant-"
# OpenAI: Should start with "sk-"
Error: 429 Too Many Requests from AI APIsSolutions:
# Check rate limiting configuration
# Edit backend/.env
AI_RATE_LIMIT_PER_MINUTE=30
AI_BURST_LIMIT=5

# Implement exponential backoff
# This is handled automatically by the Ron Cortex engine

# Monitor API usage
tail -f /var/log/clipron/api_usage.log

​
Diagnostic Tools

​
Health Check Script

#!/bin/bash
# comprehensive-health-check.sh

echo "=== Clipron AI Comprehensive Health Check ==="

# System resources
echo -e "\n=== System Resources ==="
echo "CPU Usage: $(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1)%"
echo "Memory Usage: $(free | grep Mem | awk '{printf("%.1f%%", $3/$2 * 100.0)}')"
echo "Disk Usage: $(df -h / | awk 'NR==2 {print $5}')"

# Service status
echo -e "\n=== Service Status ==="
for service in clipron nginx postgresql; do
    if systemctl is-active --quiet $service; then
        echo "✅ $service: Running"
    else
        echo "❌ $service: Not running"
        systemctl status $service --no-pager -l
    fi
done

# Network connectivity
echo -e "\n=== Network Tests ==="
curl -s -o /dev/null -w "Backend API: %{http_code} (%{time_total}s)\n" http://localhost:8000/health
curl -s -o /dev/null -w "Frontend: %{http_code} (%{time_total}s)\n" http://localhost/

# Database connectivity
echo -e "\n=== Database Test ==="
cd /opt/clipron/backend
source venv/bin/activate
python -c "
try:
    from database import engine
    engine.connect()
    print('✅ Database: Connected')
except Exception as e:
    print(f'❌ Database: {e}')
"

# Log recent errors
echo -e "\n=== Recent Errors ==="
journalctl -u clipron --since "1 hour ago" -p err --no-pager | tail -5

​
Log Analysis

# Analyze error patterns
sudo journalctl -u clipron --since "24 hours ago" | grep -i error | sort | uniq -c | sort -nr

# Monitor real-time logs
sudo journalctl -u clipron -f --output=json | jq -r '.MESSAGE'

# Check specific error types
sudo journalctl -u clipron | grep -E "(500|error|exception|failed)" | tail -20
Important: Always backup your database and configuration files before attempting major fixes. Test solutions in a staging environment when possible.
Troubleshooting Tip: When reporting issues, include the output of the health check script, relevant log entries, and your system configuration. This helps support provide faster, more accurate assistance.