Troubleshooting

This guide helps you diagnose and resolve common issues when developing and running the User Management API.

Common Issues

Port 8080 Already in Use

Error Message:

Web server failed to start. Port 8080 was already in use.

Solution 1: Kill the ProcessFind and kill the process using port 8080:

# Linux/macOS
lsof -ti:8080 | xargs kill -9

# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F

Solution 2: Change the PortUpdate application.yaml or use an environment variable:

application.yaml

server:
  port: 8081

Or via command line:

./gradlew bootRun --args='--server.port=8081'

Database Connection Failed

Error Message:

Connection to localhost:5432 refused. Check that the hostname and port are correct
and that the postmaster is accepting TCP/IP connections.

Cause: PostgreSQL is not running or not accessible.Solution 1: Start PostgreSQL

# Using Docker
docker run -d --name postgres \
  -e POSTGRES_DB=user_db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  postgres:16

# Check if it's running
docker ps

Solution 2: Verify Connection SettingsCheck application.yaml or environment variables:

application.yaml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/user_db
    username: postgres
    password: password

Solution 3: Use Docker Compose

docker compose up -d db

Java Version Mismatch

Error Message:

Unsupported class file major version 65

java.lang.UnsupportedClassVersionError

Cause: This project requires Java 21. You’re using an older version.Solution:

Check your Java version:

java -version

Install Java 21:

# Using SDKMAN!
sdk install java 21.0.2-tem
sdk use java 21.0.2-tem

# Using Homebrew (macOS)
brew install openjdk@21

# Verify installation
java -version

Set JAVA_HOME:

# Linux/macOS
export JAVA_HOME=/path/to/java-21

# Windows
set JAVA_HOME=C:\Program Files\Java\jdk-21

Flyway Migration Failed

Error Message:

FlywayException: Validate failed: Migration checksum mismatch for migration version 1

Cause: Database schema is out of sync with migration files.Solution 1: Repair Flyway

./gradlew flywayRepair

Solution 2: Clean and Rebuild (Development Only)

This will delete all data in your database. Only use in development!

# Drop and recreate database
docker exec -it postgres psql -U postgres -c "DROP DATABASE user_db;"
docker exec -it postgres psql -U postgres -c "CREATE DATABASE user_db;"

# Restart application
./gradlew bootRun

Solution 3: Baseline Existing Database

application.yaml

spring:
  flyway:
    baseline-on-migrate: true
    baseline-version: 0

MapStruct Generated Code Not Found

Error Message:

Cannot resolve symbol 'UserDtoMapperImpl'

Could not autowire. No beans of 'UserDtoMapper' type found.

Cause: MapStruct annotation processor hasn’t generated implementation classes.Solution:

Clean and rebuild the project:

./gradlew clean build

Verify annotation processors are enabled in your IDE:

IntelliJ IDEA:

Settings → Build, Execution, Deployment → Compiler → Annotation Processors
Check “Enable annotation processing”

Eclipse:

Right-click project → Properties → Java Compiler → Annotation Processing
Check “Enable project specific settings”

Rebuild the project:

./gradlew build --refresh-dependencies

Lombok Annotations Not Working

Error Message:

Cannot resolve method 'builder()'
Cannot resolve method 'getUsername()'

Cause: Lombok plugin not installed or annotation processing disabled.Solution:

IntelliJ IDEA:
- Install Lombok plugin: Settings → Plugins → Search “Lombok” → Install
- Enable annotation processing: Settings → Build → Compiler → Annotation Processors → Enable
- Restart IDE
Eclipse:
- Download lombok.jar from https://projectlombok.org/download
- Run: java -jar lombok.jar
- Select Eclipse installation directory
- Click “Install/Update”
VS Code:
- Install “Lombok Annotations Support” extension
- Reload window

Build Errors

Dependency Resolution Failed

Error Message:

Could not resolve all files for configuration ':compileClasspath'.

Solution:

# Clear Gradle cache
rm -rf ~/.gradle/caches/

# Refresh dependencies
./gradlew clean build --refresh-dependencies

Gradle Daemon Failed to Start

Error Message:

Unable to start the daemon process.

Solution:

# Stop all Gradle daemons
./gradlew --stop

# Clear Gradle daemon directory
rm -rf ~/.gradle/daemon/

# Rebuild
./gradlew build

Test Failures

Error Message:

There were failing tests. See the report at: build/reports/tests/test/index.html

Solution:

Run tests with verbose output:

./gradlew test --info

Run specific test class:

./gradlew test --tests UserServiceTest

Skip tests temporarily (not recommended):

./gradlew build -x test

Check test reports:

open build/reports/tests/test/index.html

Runtime Errors

Bean Creation Exception

Error Message:

Error creating bean with name 'userService': Unsatisfied dependency expressed through constructor parameter 0

Cause: Spring cannot find a bean to inject.Solution:

Check UserBeanConfiguration.java - ensure all required beans are defined:

src/main/java/com/fbaron/user/config/UserBeanConfiguration.java

@Bean
public UserJpaAdapter userJpaAdapter(UserJpaRepository repo, UserJpaMapper mapper) {
    return new UserJpaAdapter(repo, mapper);
}

@Bean
public UserService userService(UserQueryRepository queryRepo, 
                                UserCommandRepository cmdRepo) {
    return new UserService(queryRepo, cmdRepo);
}

Verify component scanning is enabled (it should be by default with @SpringBootApplication).
Check for circular dependencies - use constructor injection, not field injection.

Validation Errors Not Returning 400

Error Message: API returns 500 instead of 400 for invalid input.Cause: Missing @Valid annotation on controller method parameter.Solution:Ensure @Valid is present on DTO parameters:

src/main/java/com/fbaron/user/web/rest/UserRestAdapter.java

@PostMapping
public ResponseEntity<UserDto> registerUser(
        @Valid @RequestBody RegisterUserDto dto) {  // @Valid is required
    // Implementation...
}

Swagger UI Not Loading

Error Message: 404 Not Found when accessing /swagger-ui/index.htmlSolution:

Verify the dependency is present in build.gradle:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.15'

Access the correct URL:

http://localhost:8080/swagger-ui/index.html

Check if OpenAPI is configured in OpenApiConfig.java:

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI userManagementAPI() {
        // Configuration...
    }
}

CORS Errors in Browser

Error Message:

Access to fetch at 'http://localhost:8080/api/v1/users' from origin 'http://localhost:3000' 
has been blocked by CORS policy

Solution:Add CORS configuration:

src/main/java/com/fbaron/user/config/WebConfig.java

package com.fbaron.user.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("http://localhost:3000")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("*");
    }
}

Docker Issues

Docker Build Fails

Error Message:

ERROR [build 6/6] RUN ./gradlew build

Solution:

Ensure Dockerfile uses correct base image:

FROM eclipse-temurin:21-jdk-alpine AS build

Check .dockerignore doesn’t exclude necessary files:

.git
build/
.gradle/
.idea/

Build with no cache:

docker build --no-cache -t user-management-api .

Container Exits Immediately

Error Message:

docker ps shows container is not running

Solution:

Check container logs:

docker logs <container-id>

Ensure database is accessible from container:

# If using localhost, change to host.docker.internal (macOS/Windows)
# Or use Docker network
docker run -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/user_db \
  user-management-api

Use Docker Compose for better networking:

docker compose up

Cannot Connect to Database from Container

Error Message:

Connection refused: connect

Cause: Container cannot reach PostgreSQL on localhost.Solution:Use Docker Compose and service names:

docker-compose.yml

services:
  db:
    image: postgres:16
    # ...
  
  api:
    build: .
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/user_db  # Use service name
    depends_on:
      - db

Performance Issues

Slow Database Queries

Solution:

Enable SQL logging to identify slow queries:

application.yaml

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true
logging:
  level:
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE

Add database indexes:

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_active ON users(active);

Use pagination for large result sets:

public interface UserJpaRepository extends JpaRepository<UserJpaEntity, UUID> {
    Page<UserJpaEntity> findAllByActiveTrue(Pageable pageable);
}

High Memory Usage

Solution:

Limit JVM heap size:

./gradlew bootRun -Dorg.gradle.jvmargs="-Xmx512m -Xms256m"

Use streaming for large datasets:

@Transactional(readOnly = true)
public Stream<User> findAllStream() {
    return userRepository.findAll().stream();
}

Enable connection pooling in application.yaml:

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2

Getting Help

Check Logs

Review application logs for detailed error messages:

./gradlew bootRun --info

Enable Debug Mode

Run with debug logging:

logging:
  level:
    com.fbaron.user: DEBUG

Review Documentation

Check the Spring Boot docs for framework-specific issues.

Community Support

Ask questions on Stack Overflow with the spring-boot tag.

Configuration Guide

Learn about application configuration options

Testing Guide

Write tests to catch issues early

Extending the App

Add new features correctly

Deployment

Deploy to production environments

Get Started

Architecture

Guides

Development

Common Issues

Build Errors

Runtime Errors

Docker Issues

Performance Issues

Getting Help

Check Logs

Enable Debug Mode

Review Documentation

Community Support

Configuration Guide

Testing Guide

Extending the App

Deployment

Build docs developers (and LLMs) love

Get Started

Architecture

Guides

Development

​Common Issues

​Build Errors

​Runtime Errors

​Docker Issues

​Performance Issues

​Getting Help

Check Logs

Enable Debug Mode

Review Documentation

Community Support

​Related Resources

Configuration Guide

Testing Guide

Extending the App

Deployment

Build docs developers (and LLMs) love

Common Issues

Build Errors

Runtime Errors

Docker Issues

Performance Issues

Getting Help

Related Resources