How to Configure Lombok with the Maven Compiler Plugin in Spring Boot

Configure the Maven Compiler Plugin's annotationProcessorPaths with Lombok listed before the Spring Boot configuration processor to ensure proper code generation order.

Configuring Lombok with the Maven Compiler Plugin in a Spring Boot project requires specific attention to annotation processor ordering to ensure compatibility with the framework's metadata generation. According to the spring-projects/spring-boot source code, the Lombok annotation processor must run before the spring-boot-configuration-processor during compilation to correctly generate getters, setters, and constructors that Spring Boot can analyze for @ConfigurationProperties.

Understanding the Annotation Processor Order

The Spring Boot documentation explicitly defines the required execution order for annotation processors when Lombok is present. In documentation/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc at line 77, the documentation states:

If you are using Lombok in your project, you need to make sure that its annotation processor runs before spring-boot-configuration-processor.

This ordering ensures that Lombok generates its boilerplate code (getters, setters, constructors) before the Spring Boot processor analyzes the class for configuration metadata. The same documentation file at line 94 also confirms that the Spring Boot processor recognizes specific Lombok annotations including @Data, @Value, @Getter, and @Setter.

Step-by-Step Maven Configuration

Add the Lombok Dependency

Declare Lombok as a compile-only dependency in your pom.xml. Since Lombok generates code at compile time, it is not required at runtime and should use provided scope.

<properties>
    <lombok.version>1.18.34</lombok.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>${lombok.version}</version>
        <scope>provided</scope>
    </dependency>
    
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

Configure the Maven Compiler Plugin

Explicitly define the annotationProcessorPaths in the Maven Compiler Plugin configuration. The critical requirement is listing Lombok first in the processor paths, followed by the Spring Boot configuration processor.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <!-- Lombok must run first -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <!-- Spring Boot processor runs after Lombok -->
                    <path>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-configuration-processor</artifactId>
                        <version>${spring-boot.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

The annotationProcessorPaths element ensures that Maven uses the exact versions specified, avoiding classpath conflicts that can occur when processors are discovered automatically from the project dependencies.

Complete Configuration Example

Below is a minimal but complete pom.xml configuration that demonstrates the proper setup for a Spring Boot project using Lombok:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/>
    </parent>
    
    <groupId>com.example</groupId>
    <artifactId>lombok-demo</artifactId>
    <version>1.0.0</version>
    
    <properties>
        <java.version>17</java.version>
        <lombok.version>1.18.34</lombok.version>
    </properties>
    
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
            <scope>provided</scope>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                        <path>
                            <groupId>org.springframework.boot</groupId>
                            <artifactId>spring-boot-configuration-processor</artifactId>
                            <version>${spring-boot.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Verification

After configuring the plugin, verify the setup by compiling the project:

./mvnw clean compile

Check that Lombok-generated methods appear in your IDE without errors and that the Spring Boot configuration processor successfully processes any @ConfigurationProperties classes annotated with Lombok. The compiled classes in target/classes should contain the generated bytecode for getters, setters, and constructors.

Summary

• Processor ordering is critical: Lombok must run before spring-boot-configuration-processor as documented in annotation-processor.adoc lines 77 and 94.
• Use annotationProcessorPaths: Explicitly declare processor paths in the Maven Compiler Plugin to control execution order and versioning.
• Scope matters: Declare Lombok with provided scope since it is only needed at compile time.
• Supported annotations: Spring Boot recognizes @Data, @Value, @Getter, and @Setter from Lombok when generating configuration metadata.

Frequently Asked Questions

Why must Lombok run before the Spring Boot configuration processor?

The Spring Boot configuration processor analyzes classes to generate configuration metadata for application.properties and application.yml auto-completion. If the processor runs before Lombok, it sees the raw source code without the generated getters and setters, causing it to miss configuration properties that rely on Lombok-generated accessors. As implemented in spring-projects/spring-boot, the processor at configuration-metadata/spring-boot-configuration-processor/src/test/java/.../LombokSimpleDataProperties.java expects Lombok-generated code to be present during analysis.

Can I use Lombok with Spring Boot without explicit annotationProcessorPaths?

While Maven can automatically detect annotation processors from the classpath, this approach does not guarantee the execution order required by Spring Boot. Without explicit annotationProcessorPaths, the processors may run in an arbitrary order, potentially causing the Spring Boot processor to execute before Lombok and fail to detect configuration properties. The explicit configuration ensures compatibility as specified in the Spring Boot documentation.

Which Lombok annotations are supported by Spring Boot's configuration processor?

According to documentation/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc at line 94, the Spring Boot configuration processor specifically supports @Data, @Value, @Getter, and @Setter. These annotations generate the accessor methods that the processor recognizes when scanning for configuration properties metadata.

Should Lombok be included in the final artifact?

No. Lombok should always use provided scope (or compileOnly in Gradle) because it performs source-code transformations during compilation and is not required at runtime. The spring-boot-configuration-processor should also be marked as <optional>true</optional> to prevent it from being packaged in the final artifact, as it is only needed during the build process to generate metadata.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}