Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Introduction

Bean creation is a core part of how Spring initializes application components. However, when using the @Mapper annotation from MapStruct, we might encounter unexpected bean creation errors during application startup. These issues are typically triggered when Spring doesn’t correctly detect, instantiate, or wire MapStruct-generated mapper implementations. As a result, the application may fail to start, or various runtime exceptions may be raised, indicating that missing or improperly configured mapper beans are present.

In this tutorial, we’ll explore how to effectively resolve issues when creating beans, caused by the @Mapper annotation of MapStruct in Spring applications. Specifically, the focus will be on configuring mappers so that Spring properly detects, instantiates, and wires them, ensuring smooth application startup. Along the way, practical solutions and best practices will demonstrate how to prevent common runtime exceptions, enhance maintainability, and fully leverage the compile-time mapping capabilities of MapStruct.

2. How MapStruct Interacts With Spring Beans

Before we address the issues, it’s essential to understand how MapStruct operates and why Spring sometimes fails to recognize its generated mappers.

2.1. How MapStruct Generates Mappers

MapStruct acts as a compile-time annotation processor that transforms mapping interfaces into concrete implementations.

To illustrate this, consider a simple domain consisting of a Person entity and its corresponding PersonDto class:

public class Person {
    private String name;
    private int age;

    // Constructors, getters, and setters
}

public class PersonDto {
    private String name;
    private int age;

    // Constructors, getters, and setters
}

A mapper interface defines the transformation between these two types:

@Mapper
public interface PersonMapper {
    PersonDto toDto(Person person);
}

During compilation, MapStruct creates a class named PersonMapperImpl inside the generated sources directory. This generated class contains the actual field-mapping logic required to convert a Person entity into a PersonDto object. However, despite being available in the generated sources, the implementation remains a plain Java class without any Spring-specific annotations. Consequently, Spring doesn’t include the mapper in its application context and doesn’t manage its lifecycle.

2.2. Why Bean Creation Fails

The Spring dependency injection mechanism expects all required beans to be registered within the application context.

Let’s consider a service that declares a dependency on the mapper:

@Autowired
private PersonMapper personMapper;

When Spring attempts to inject this dependency, it triggers a NoSuchBeanDefinitionException. This happens because MapStruct doesn’t register the generated mapper implementations as Spring beans by default. Since the generated PersonMapperImpl lacks a Spring-specific annotation, the Spring container doesn’t detect it during component scanning.

There are several consequences of this:

  • Spring cannot locate the mapper implementation.
  • Dependency injection fails.
  • Application startup may break with missing-bean errors.

This challenge highlights the need to align the generated MapStruct code with the lifecycle of a Spring bean.

3. Configuring MapStruct Mappers for Spring

To fix the bean creation error discussed in the previous section, MapStruct must be configured to produce mapper implementations that Spring recognizes as managed beans.

3.1. Enabling the Spring Component Model

MapStruct generates Spring–managed mapper beans by specifying componentModel = “spring” in the @Mapper annotation:

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

With this configuration, MapStruct generates the implementation that we need:

@Component
public class PersonMapperImpl implements PersonMapper { ... }

In this case, the @Component annotation registers the generated mapper so that Spring treats it as a managed bean. As a result, it becomes part of the application context, making it available for injection into dependent services or controllers. This configuration bridges the MapStruct compile-time implementation with the Spring runtime dependency management, eliminating missing-bean errors and ensuring consistent mapper availability across the application.

3.2. Ensuring Annotation Processing Is Enabled

Even with the correct component model, MapStruct cannot generate mapper implementations without annotation processing. Annotation processors execute during compilation to produce the required classes. Without this configuration, the interfaces compile successfully, but the implementations don’t exist, preventing Spring from registering the beans.

Projects using Maven typically rely on the maven-compiler-plugin to execute the MapStruct annotation processor:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.10.1</version>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>${mapstruct.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

This configuration ensures that MapStruct generates all mapper implementations during the compile phase.

For Gradle-based projects, annotation processing depends on another setup (depending on the version):

dependencies {
    annotationProcessor 'org.mapstruct:mapstruct-processor:${mapstruct.version}'
}

Adding this dependency enables Gradle to execute the MapStruct code generator during compilation, producing mapper implementations that Spring detects and registers as managed beans.

4. Common Bean Creation Issues and Their Solutions

Even after configuring MapStruct and enabling annotation processing, certain bean-creation issues may persist in Spring applications. The following subsections outline the most common causes and their corresponding solutions.

4.1. Package Not Scanned by Spring

Spring Boot automatically scans packages under the package of the main application class. If the mappers are located outside this path, Spring doesn’t detect them, resulting in a NoSuchBeanDefinitionException when trying to inject the mapper.

To fix this, we can ensure that all mapper interfaces are placed within a package scanned by Spring, or explicitly define the packages to scan:

@SpringBootApplication(scanBasePackages = "com.example")

This way, we enable Spring to detect and register MapStruct mappers as beans correctly.

4.2. Conflicts Between Lombok and MapStruct

Projects that combine Lombok and MapStruct often encounter subtle compilation issues, leading to bean creation failures. Since both Lombok and MapStruct rely on annotation processors, any conflict or incorrect processor order may lead to different issues:

  • incomplete model classes
  • missing getters or setters
  • incorrect mapping behavior

Hence, let’s configure the Lombok annotation processor to execute before MapStruct:

<annotationProcessorPaths>
    <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </path>
    <path>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
    </path>
</annotationProcessorPaths>

When using Maven, this adjustment should ensure that all model classes are fully generated before MapStruct creates the mapper implementations, eliminating common bean injection issues in Spring applications.

4.3. IDE Annotation Processing Issues

IDE-level annotation processing often prevents MapStruct from generating mapper implementations, even when Maven or Gradle is configured correctly. Many IDEs disable it by default. This situation results in missing *MapperImpl files, bean creation failures, and compilation errors in the IDE.

To resolve such problems, we enable annotation processing in the IDE settings so that MapStruct can automatically generate the required mapper implementations.

5. Conclusion

In this article, we examined how the MapStruct @Mapper annotation interacts with the Spring bean creation process and why mapper implementations sometimes fail to load correctly during application startup. MapStruct generates mapper implementations at compile time, and if Spring doesn’t detect them correctly, a bean error occurs. By configuring the @Mapper annotation with component model and ensuring annotation processing is active in both build tools and IDEs, the generated mappers integrate seamlessly into the Spring application context.

Furthermore, resolving common issues such as mappers placed outside scanned packages, conflicts with Lombok, and annotation processing problems in the IDE stabilizes the mapping layer and avoids runtime bean errors. As a result, proper configuration and build setup, aligned with Spring scanning and injection mechanisms, guarantee the reliable availability of mapper beans.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW