alex
33342d1611
- .gitignore: add .drive-scratch.js (automated scratch file) - package.json/package-lock.json: dependency updates - docs/troubleshooting.md: documentation updates - src/tests/login.test.js: login flow integration test - src/tests/playthroughRun2.js: full mission playthrough simulation
343 lines
5.1 KiB
Markdown
343 lines
5.1 KiB
Markdown
# 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
|
|
```
|