dwroller/docs/troubleshooting.md

Troubleshooting Guide

Common issues and their solutions for Deathwatch Roller.

Production site blank (dwroller.alw.dk)? See incident-2026-07-04-blank-site.md for a real case: an autofs idle-unmount on /nas crash-looping the PM2 process, plus a webpack CJS/ESM interop bug in a component that require()'d a shared CommonJS module, throwing before React could mount.

Application Won't Start

Port Already in Use

# Check what's using port 3000 or 5000
lsof -i :3000
lsof -i :5000

# Kill the process or change the port in .env
kill -9 <PID>

Dependencies Not Installed

# Reinstall dependencies
npm install

# Or update existing
npm install --save

Node Version Too Old

# Check Node version
node --version

# Requires Node.js 18+ (check package.json for version)

# Upgrade Node
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Database Errors

Database Not Found

# Check if database directory exists
ls -la database/

# The database is created automatically on first run
# If missing, remove it to recreate
rm database/data.db

Corrupted Database

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

# Recreate database
rm database/data.db
# Application will recreate on restart

Frontend Issues

Cache Not Updating

# Clear build cache
rm -rf .next/
rm -rf frontend/node_modules/.cache/

# Rebuild
npm run build
npm start

Styles Not Loading

Check that vite.config.js or webpack is configured correctly for asset handling.

Build Fails

# Clean and rebuild
rm -rf node_modules
rm -rf frontend/node_modules
npm install
npm run build

Backend Issues

Database Connection Failed

# Check .env file
cat .env

# Verify database path exists
ls -la $DATABASE_PATH

Server Logs Show Errors

# Check backend logs
tail -f backend.log

# Clear logs
> backend.log

Authentication Issues

Cannot Login

• Verify .env has SESSION_SECRET set
• Check if password is correct
• Try password reset

# Reset session secret
NODE_ENV=development npm run server

Session Expires Too Soon

# Check session config in server.js
# Increase maxAge in cookie config

API Issues

CORS Errors

# Check CORS configuration in server.js
# Ensure frontend origin is allowed

API Endpoints Not Working

# Test API directly
curl http://localhost:5000/api/players

# Check backend logs
tail -f backend.log

Deployment Issues

PM2 Not Starting

# Check ecosystem.config.js exists
ls ecosystem.config.js

# View PM2 logs
pm2 logs

# Restart apps
pm2 restart all

Build Fails in Production

# Clean build
npm run clean
npm run build

# Check for build errors
npm run build 2>&1

Performance Issues

Application is Slow

# Check for memory leaks
pm2 monitortype --interval 10000

# Check database queries
# Add indexes to frequently queried fields

# Enable compression
npm install compression
app.use(compression());

High CPU Usage

# Identify the process
ps aux | grep node

# Check for infinite loops in code
# Review recent deployments

Browser Issues

Styles Not Applying

• Clear browser cache (Ctrl+Shift+Delete)
• Try incognito mode
• Check browser console for errors

JavaScript Console Errors

# Check frontend code for syntax errors
cd frontend
npm run lint

# Check browser DevTools
# Network tab for failed requests

Production Issues

Application Crashes on Restart

# Check error logs
pm2 logs --err

# Enable better error logging
NODE_ENV=production npm run start

Memory Issues

# Monitor memory usage
pm2 monitortype --interval 10000

# Increase max_memory_restart in ecosystem.config.js
max_memory_restart: '1G'

Development Issues

TS Errors

# Type check
cd backend
npx tsc --noEmit

# Fix errors in .ts files

E2E Tests Failing

# Run tests in debug mode
npm run test:e2e -- --debug

# Check test logs
npm run test:e2e

Quick Fixes

Reset Everything

# Stop all services
pm2 stop all

# Clear caches
rm -rf .next/
rm -rf frontend/node_modules/.cache/

# Recreate database
rm database/data.db

# Reinstall
npm install

# Restart
npm run pm2:start

Debug Mode

# Enable verbose logging
NODE_ENV=development npm run dev

# Watch mode
npm run dev

Getting Help

1. Check the logs: tail -f backend.log
2. Review the Developer Guide
3. Search for issues on GitHub
4. Create a new issue with:
   • Steps to reproduce
   • Expected vs actual behavior
   • Logs and error messages

Common Error Messages

"Cannot find module"

npm install
# or
npm install --save <missing-package>

"EADDRINUSE"

# Check what's using the port
lsof -i :<port>
kill -9 <PID>

"Database connection failed"

# Check .env has correct database path
cat .env | grep DATABASE_PATH
# Or set it explicitly
DATABASE_PATH=./database/data.db