Troubleshooting Guide - jnleyva816/NextMove GitHub Wiki
This guide helps you diagnose and resolve common issues when working with the NextMove project. Issues are organized by category with step-by-step solutions.
Problem: docker-compose up
fails with port conflicts
Error: Port 8080 is already in use
Solution:
# Check what's using the port
sudo netstat -tulpn | grep :8080
sudo lsof -i :8080
# Kill the process using the port
sudo kill -9 <PID>
# Or change ports in docker-compose.yml
# Change port mapping from "8080:8080" to "8081:8080"
Problem: docker-compose up
fails with permission denied
Error: Permission denied while trying to connect to Docker daemon
Solution:
# Add user to docker group
sudo usermod -aG docker $USER
# Restart docker service
sudo systemctl restart docker
# Log out and log back in for changes to take effect
Problem: Services fail to start with "network not found"
Error: network nextmove_default not found
Solution:
# Clean up docker networks
docker network prune
# Remove all containers and restart
docker-compose down --remove-orphans
docker-compose up -d
Problem: Backend cannot connect to database
Error: Connection refused to database
Solution:
# Check if PostgreSQL is running
docker-compose ps
# Check database logs
docker-compose logs postgres
# Verify environment variables
cat backend/.env
# Test database connection
docker exec -it nextmove_postgres_1 psql -U postgres -d nextmove
Problem: Database authentication failed
Error: FATAL: password authentication failed for user "postgres"
Solution:
# Reset database container
docker-compose down -v
docker-compose up -d postgres
# Wait for database to initialize
sleep 30
# Check if database is ready
docker exec -it nextmove_postgres_1 pg_isready -U postgres
Problem: Database schema not created
Error: Table 'users' doesn't exist
Solution:
# Check if backend is properly connected
curl http://localhost:8080/actuator/health
# Check backend logs for migration errors
docker-compose logs backend
# Manually run migrations if needed
cd backend
./mvnw flyway:migrate
# Or recreate database with proper schema
docker-compose down -v
docker-compose up -d
Problem: Maven build fails with compilation errors
Error: [ERROR] COMPILATION ERROR
Solution:
# Clean and rebuild
cd backend
./mvnw clean compile
# Check Java version
java -version
# Should be Java 17 or higher
# Update Maven wrapper
./mvnw wrapper:wrapper
# Clear Maven cache
rm -rf ~/.m2/repository
./mvnw clean install
Problem: Tests fail with database connection
Error: Unable to obtain connection from database
Solution:
# Check if test profile is configured
cat backend/src/test/resources/application-test.yml
# Run tests with correct profile
./mvnw test -Dspring.profiles.active=test
# Or run tests with H2 database
./mvnw test -Dspring.datasource.url=jdbc:h2:mem:testdb
Problem: Application fails to start with port binding error
Error: Port 8080 was already in use
Solution:
# Change server port in application.properties
echo "server.port=8081" >> backend/src/main/resources/application.properties
# Or set via environment variable
export SERVER_PORT=8081
./mvnw spring-boot:run
Problem: JWT authentication not working
Error: JWT token validation failed
Solution:
# Check JWT secret configuration
grep JWT_SECRET backend/.env
# Generate new JWT secret (minimum 256 bits)
openssl rand -base64 32
# Update .env file with new secret
echo "JWT_SECRET=your-new-secret-here" >> backend/.env
# Restart application
docker-compose restart backend
Problem: CORS errors when accessing from frontend
Error: Access to XMLHttpRequest blocked by CORS policy
Solution:
# Check CORS configuration in SecurityConfig.java
# Add frontend URL to allowed origins
# Or temporarily disable CORS for debugging
# Add @CrossOrigin annotation to controllers
# Restart backend after changes
docker-compose restart backend
Problem: npm run dev
fails with module not found errors
Error: Cannot find module 'react'
Solution:
# Clear node_modules and reinstall
cd frontend
rm -rf node_modules package-lock.json
npm install
# Check Node.js version
node --version
# Should be Node.js 20 or higher
# Clear npm cache
npm cache clean --force
Problem: Vite dev server fails to start
Error: Port 5173 is already in use
Solution:
# Use different port
npm run dev -- --port 3001
# Or kill process using the port
sudo lsof -i :5173
sudo kill -9 <PID>
# Configure custom port in vite.config.ts
# server: { port: 3001 }
Problem: TypeScript compilation errors
Error: Type 'string | undefined' is not assignable to type 'string'
Solution:
# Run type checking
npm run type-check
# Fix type errors in code
# Use optional chaining and nullish coalescing
const value = data?.property ?? 'default';
# Update TypeScript configuration if needed
# Check tsconfig.json for strict settings
Problem: Build fails with out of memory error
Error: JavaScript heap out of memory
Solution:
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build
# Or add to package.json scripts
"build": "NODE_OPTIONS='--max-old-space-size=4096' vite build"
Problem: API requests fail with network errors
Error: NetworkError when attempting to fetch resource
Solution:
# Check if backend is running
curl http://localhost:8080/actuator/health
# Verify API URL configuration
cat frontend/.env
# Should have VITE_API_URL=http://localhost:8080
# Check browser network tab for detailed error
# Enable CORS if needed (see backend section)
Problem: Routes not working after page refresh
Error: Cannot GET /dashboard
Solution:
# Configure server to handle client-side routing
# For nginx, add try_files directive:
location / {
try_files $uri $uri/ /index.html;
}
# For development server, this is handled by Vite automatically
# Check that React Router is properly configured
Problem: Jest/Vitest tests fail with module resolution
Error: Cannot find module '@/components/Button'
Solution:
# Check vite.config.ts or vitest.config.ts for path aliases
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
}
# Or update tsconfig.json paths
"paths": {
"@/*": ["./src/*"]
}
Problem: Tests fail with DOM environment errors
Error: document is not defined
Solution:
# Configure test environment in vitest.config.ts
test: {
environment: 'jsdom',
setupFiles: ['./src/test/setup.ts']
}
# Install required packages
npm install -D jsdom @testing-library/jest-dom
Problem: Playwright tests fail with browser launch errors
Error: Browser executable not found
Solution:
# Install Playwright browsers
npx playwright install
# Or install specific browser
npx playwright install chromium
# Check system dependencies
npx playwright install-deps
Problem: E2E tests fail with timeout errors
Error: Test timeout of 30000ms exceeded
Solution:
# Increase timeout in playwright.config.ts
timeout: 60000
# Or wait for specific elements
await page.waitForSelector('[data-testid="loading"]', { state: 'detached' });
# Use page.waitForLoadState()
await page.waitForLoadState('networkidle');
Problem: Docker build fails with permission denied
Error: permission denied while trying to connect to Docker daemon
Solution:
# Check Docker daemon status
sudo systemctl status docker
# Start Docker if not running
sudo systemctl start docker
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
Problem: Docker build fails with space issues
Error: no space left on device
Solution:
# Clean up Docker system
docker system prune -a
# Remove unused images
docker image prune -a
# Remove unused volumes
docker volume prune
# Check disk space
df -h
Problem: Container exits immediately
Status: Exited (1) 2 minutes ago
Solution:
# Check container logs
docker logs nextmove_backend_1
# Run container interactively for debugging
docker run -it jleyva816/nextmove-backend:latest /bin/bash
# Check if all environment variables are set
docker exec -it nextmove_backend_1 env
Problem: Container networking issues
Error: Connection refused between containers
Solution:
# Check if containers are on same network
docker network ls
docker network inspect nextmove_default
# Use service names for internal communication
# Instead of localhost, use service name (e.g., "postgres", "backend")
# Test connectivity between containers
docker exec -it nextmove_backend_1 ping postgres
Problem: Token expired errors
Error: JWT token has expired
Solution:
# Check token expiration settings
grep JWT_EXPIRATION backend/.env
# Increase expiration time (in milliseconds)
# 24 hours = 86400000ms
echo "JWT_EXPIRATION=86400000" >> backend/.env
# Clear browser storage and login again
# localStorage.clear() in browser console
Problem: CORS policy errors
Error: blocked by CORS policy
Solution:
# Update CORS configuration in backend
# Allow frontend origin in SecurityConfig.java
@CrossOrigin(origins = {"http://localhost:3000", "http://localhost:5173"})
# Or configure globally in application.yml
cors:
allowed-origins: "*"
allowed-methods: "*"
allowed-headers: "*"
Problem: Environment variables not loaded in production
Error: VITE_API_URL is undefined
Solution:
# Check if .env.production exists
ls -la frontend/.env*
# Build with correct environment
npm run build
# For Docker builds, pass env vars as build args
docker build --build-arg VITE_API_URL=https://api.yourdomain.com .
Problem: Static files not served correctly
Error: 404 for JS/CSS files
Solution:
# Check nginx configuration
# Ensure correct paths for static assets
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# Verify build output
ls -la frontend/dist/
Problem: API responses are slow
Response time > 5 seconds
Solution:
# Enable SQL logging in backend
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE
# Add database indexes for frequently queried columns
CREATE INDEX idx_applications_user_id ON job_applications(user_id);
CREATE INDEX idx_applications_status ON job_applications(status);
# Check query execution plans
EXPLAIN ANALYZE SELECT * FROM job_applications WHERE user_id = ?;
Problem: Application using too much memory
OutOfMemoryError in logs
Solution:
# Set JVM memory limits for backend
docker run -e JAVA_OPTS="-Xmx512m -Xms256m" jleyva816/nextmove-backend:latest
# For frontend, optimize bundle size
npm run build:analyze
# Check for memory leaks in browser
# Use Chrome DevTools Memory tab
# Enable debug logging
logging.level.com.jnleyva.nextmove=DEBUG
# Connect remote debugger
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar app.jar
# Profile with JVisualVM
jvisualvm --jdkhome $JAVA_HOME
# Enable React DevTools
# Install browser extension
# Enable Vite debug mode
DEBUG=vite:* npm run dev
# Check bundle analyzer
npm run build -- --mode=analyze
If you can't resolve your issue:
- Search existing issues: Check GitHub Issues
- Check logs: Always include relevant logs when asking for help
- Provide context: Include your OS, versions, and steps to reproduce
- Create minimal reproduction: Isolate the problem if possible
When reporting issues, include:
# System information
uname -a
docker --version
node --version
java -version
# Project information
git rev-parse HEAD
cat docker-compose.yml
cat frontend/package.json | grep version
cat backend/pom.xml | grep version
# Logs
docker-compose logs backend
docker-compose logs frontend
This troubleshooting guide is regularly updated with new solutions. If you solve an issue not covered here, please consider contributing the solution!