Fixing MapStruct Mapper Bean Creation in Spring Applications

Fixing Bean Creation Issues With MapStruct @Mapper Annotations in Spring Applications

Spring fails to detect MapStruct mappers by default, leading to NoSuchBeanDefinitionException during application startup. MapStruct generates mapper implementations at compile time, but they are not registered as Spring beans unless explicitly configured.

Why This Matters

MapStruct acts as a compile-time annotation processor, generating concrete implementations for mapping interfaces. However, these implementations are plain Java classes without Spring annotations, so Spring cannot manage them as beans. This mismatch causes dependency injection failures and application startup errors. The cost of this oversight is significant: runtime exceptions and potential downtime if mappers are critical to application flow.

Key Insights

• “Spring doesn’t register MapStruct mappers by default, 2025”
• “Use componentModel = ‘spring’ for Spring-managed mappers”
• “Lombok conflicts with MapStruct if annotation processors are not ordered correctly”

Working Example

@Mapper(componentModel = "spring")
public interface PersonMapper {
    PersonDto toDto(Person person);
}

@Component
public class PersonMapperImpl implements PersonMapper {
    // Generated mapping logic
}

Practical Applications

• Use Case: Spring Boot applications using MapStruct for DTO mapping
• Pitfall: Forgetting to enable annotation processing in build tools, leading to missing mapper beans

References:

• https://www.baeldung.com/spring-mapstruct-mapper-bean-creation

---