# Troubleshooting Guide

Common issues and their solutions for Deathwatch Roller.

> **Production site blank (dwroller.alw.dk)?** See
> [`incident-2026-07-04-blank-site.md`](./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

```bash
# 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

```bash
# Reinstall dependencies
npm install

# Or update existing
npm install --save
```

### Node Version Too Old

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

## Backend Issues

### Database Connection Failed

```bash
# Check .env file
cat .env

# Verify database path exists
ls -la $DATABASE_PATH
```

### Server Logs Show Errors

```bash
# 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

```bash
# Reset session secret
NODE_ENV=development npm run server
```

### Session Expires Too Soon

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

## API Issues

### CORS Errors

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

### API Endpoints Not Working

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

# Check backend logs
tail -f backend.log
```

## Deployment Issues

### PM2 Not Starting

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

# View PM2 logs
pm2 logs

# Restart apps
pm2 restart all
```

### Build Fails in Production

```bash
# Clean build
npm run clean
npm run build

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

## Performance Issues

### Application is Slow

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Check error logs
pm2 logs --err

# Enable better error logging
NODE_ENV=production npm run start
```

### Memory Issues

```bash
# Monitor memory usage
pm2 monitortype --interval 10000

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

## Development Issues

### TS Errors

```bash
# Type check
cd backend
npx tsc --noEmit

# Fix errors in .ts files
```

### E2E Tests Failing

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

# Check test logs
npm run test:e2e
```

## Quick Fixes

### Reset Everything

```bash
# 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

```bash
# 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](./developer-guide.md)
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"

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

### "EADDRINUSE"

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

### "Database connection failed"

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