Common issues and solutions for the Dissensus AI Debate Engine.

Symptoms:

• Debate appears to start but no text appears
• Browser shows loading spinner indefinitely
• Works locally but not on VPS

Cause: Nginx buffering is not disabled for the SSE endpoint.

Solution:

Verify your Nginx config has these settings in the /api/debate/stream location block:

location /api/debate/stream {
 proxy_pass http://127.0.0.1:3000;
 proxy_http_version 1.1;
 
 # CRITICAL for SSE streaming — disable all buffering
 proxy_buffering off;
 proxy_cache off;
 chunked_transfer_encoding off;
 
 proxy_read_timeout 600s;
 proxy_send_timeout 600s;
}

Then reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Symptoms:

• Debate stops mid-stream with "timeout" error
• Connection drops after ~60 seconds
• Error in browser console: net::ERR_EMPTY_RESPONSE

Cause: Nginx or client timeout is shorter than the debate duration.

Solution:

1. Increase Nginx timeout (should already be 600s):

proxy_read_timeout 600s;
proxy_send_timeout 600s;

2. Increase client-side timeout if using fetch/EventSource directly.

3. Verify the Node.js server isn't hitting a timeout:

pm2 logs dissensus --lines 50

Symptoms:

• Error: "API key required"
• Error: "Invalid API key"
• 401 Unauthorized responses

Solutions:

Missing server-side key:

# Check if .env exists and has keys
cat ~/dissensus-engine/.env
# If missing, add them
nano ~/dissensus-engine/.env

Add at least one key:

DEEPSEEK_API_KEY=sk-your-key-here

Key not loading:

# Restart the application
pm2 restart dissensus
# Verify keys are loaded
pm2 logs dissensus
# Look for: "🔑 Server-side keys configured for: deepseek"

Invalid key format:

• DeepSeek keys start with sk-
• OpenAI keys start with sk-
• Gemini keys start with AIza

Symptoms:

• Browser error: CORS policy: No 'Access-Control-Allow-Origin' header
• Requests blocked when calling API from different domain

Cause: The engine expects to serve its own frontend. Cross-origin requests may be blocked.

Solution:

The engine uses Helmet for security. If you need to enable CORS for specific origins:

1. Install CORS middleware:

cd ~/dissensus-engine
npm install cors

2. Edit server/index.js and add:

const cors = require('cors');
// Add after helmet middleware
app.use(cors({
 origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
 methods: ['GET', 'POST'],
 allowedHeaders: ['Content-Type']
}));

3. Restart:

pm2 restart dissensus

Symptoms:

• pm2 status shows "errored"
• Site returns 502 Bad Gateway
• Logs show JavaScript errors

Debugging:

# View recent logs
pm2 logs dissensus --lines 100
# Check for specific errors
pm2 logs dissensus --err
# View process details
pm2 describe dissensus

Common fixes:

Missing dependencies:

cd ~/dissensus-engine
npm install --production
pm2 restart dissensus

Port already in use:

# Find what's using port 3000
sudo ss -tlnp | grep 3000
# Kill the process or change PORT in .env
nano ~/dissensus-engine/.env # Change PORT=3001
pm2 restart dissensus

Out of memory:

# Check memory usage
free -h
# Add swap space
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Symptoms:

• Browser shows "Not Secure" warning
• Certbot fails to obtain certificate
• HTTPS redirects to HTTP

Solutions:

Certificate expired:

# Renew manually
sudo certbot renew
# Or force renewal
sudo certbot renew --force-renewal
# Test auto-renewal
sudo certbot renew --dry-run

Certbot fails to obtain certificate:

1. Verify domain points to VPS:

dig app.dissensus.fun +short
# Should return YOUR_VPS_IP

2. Verify port 80 is open:

sudo ufw status | grep 80

3. Try with verbose output:

sudo certbot --nginx -d app.dissensus.fun -v

Mixed content warnings:

Ensure all resources load over HTTPS. The engine serves its own assets, so this is usually not an issue unless you've modified the frontend.

Symptoms:

• Error: "Too many debates. Please wait a minute and try again."
• HTTP 429 responses
• Works after waiting 60 seconds

Cause: Default rate limit is 10 debates per minute in production.

Solution:

This is expected behavior to prevent abuse. If you need higher limits for legitimate use:

Edit server/index.js:

const debateLimiter = rateLimit({
 windowMs: 60 * 1000,
 max: 20, // Increase from 10 to 20
 message: { error: 'Too many debates. Please wait a minute and try again.' }
});

Then restart:

pm2 restart dissensus

# PM2 status
pm2 status
# Process details
pm2 describe dissensus
# Live logs
pm2 logs dissensus -f
# Last 100 lines
pm2 logs dissensus --lines 100

# Health check
curl http://localhost:3000/api/health
# Test debate stream (quick)
curl "http://localhost:3000/api/debate/stream?topic=test&apiKey=YOUR_KEY&provider=deepseek" | head -5
# Test debate validation
curl -X POST http://localhost:3000/api/debate/validate \
 -H "Content-Type: application/json" \
 -d '{"topic": "Is AI safe?", "provider": "deepseek"}'
# Check providers
curl http://localhost:3000/api/providers | python3 -m json.tool
# Get metrics
curl http://localhost:3000/api/metrics

# Test configuration syntax
sudo nginx -t
# Check Nginx status
sudo systemctl status nginx
# View error logs
sudo tail -f /var/log/nginx/error.log
# View access logs
sudo tail -f /var/log/nginx/access.log
# Reload configuration
sudo systemctl reload nginx

# List certificates
sudo certbot certificates
# Check certificate expiry
openssl x509 -in /etc/letsencrypt/live/app.dissensus.fun/fullchain.pem -noout -dates
# Test SSL connection
curl -vI https://app.dissensus.fun

# Disk space
df -h
# Memory usage
free -h
# CPU and processes
htop
# Node.js process
ps aux | grep node
# Network connections
sudo ss -tlnp | grep -E '3000|80|443'
# Uptime
uptime

Already enabled in recommended Nginx config. Verify:

gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css application/json application/javascript;

Already configured in recommended Nginx config. Assets are cached:

• CSS/JS: 7 days
• Images: 30 days

For high-traffic deployments, run multiple Node.js processes:

pm2 start server/index.js --name dissensus -i 2

This creates 2 instances. Ensure your code is stateless (it is by default).

The engine is stateless by default. If you add persistent storage:

• Use Redis for session storage
• Use PostgreSQL for structured data
• Keep the debate engine itself stateless

Track your AI provider usage:

At 100 debates/day with DeepSeek: ~24ドル/month

Q: Can I run the engine without Nginx?

Yes, but not recommended for production. Set TRUST_PROXY=0 in .env and ensure port 3000 is accessible. You'll lose SSL termination and static file optimization.

Q: How do I change the port?

Edit .env:

PORT=8080

Update Nginx config to proxy to the new port, then restart both services.

Q: Can I use multiple AI providers at once?

The engine uses one provider per debate. Configure multiple keys in .env and users can select their preferred provider in the UI.

Q: How do I backup the application?

# Create backup
tar -czf dissensus-backup-$(date +%Y%m%d).tar.gz ~/dissensus-engine
# Exclude node_modules to save space
tar -czf dissensus-backup-$(date +%Y%m%d).tar.gz --exclude='node_modules' ~/dissensus-engine

Q: The debate seems slower than expected.

Check:

1. Which provider/model you're using (DeepSeek is fastest)
2. Your VPS network latency to the AI provider
3. If you're hitting rate limits on the AI provider side

Q: Can I disable specific providers?

Simply don't set their API keys in .env. They won't appear in the UI.

Q: How do I update the "Debate of the Day" topic?

The topic is automatically generated from CoinGecko trending data. To customize, edit server/debate-of-the-day.js or set a static topic.

Q: What if my API key is compromised?

1. Revoke the key immediately at your provider's dashboard
2. Generate a new key
3. Update .env with the new key
4. Restart: pm2 restart dissensus

If you encounter an issue not covered here:

1. Check the logs: pm2 logs dissensus --lines 200
2. Test locally first to isolate VPS-specific issues
3. Verify your .env configuration
4. Check Nginx error logs: sudo tail -f /var/log/nginx/error.log

Built for Dissensus — Where AI agents disagree so you don't have to. 🔴🟢🔵