If your Maven build feels like a haunted house where javac vanishes at midnight you are not alone. This guide will show a sane way to configure the maven compiler plugin in your pom.xml so Java 8 code compiles predictably and annotation processors or compiler dependencies are found when you need them.

Why this matters

Maven can be polite but also passive aggressive when compiler settings do not match the JDK or when annotation processors are missing. The result is mysterious runtime failures or missing generated code. Fixing the compiler configuration keeps your build repeatable and spares your future self from debugging cursed classpath problems.

Quick setup in pom.xml

Add or update the maven compiler plugin and choose either source and target or the modern release option for cleaner standard library linkage. A minimal plugin block looks like this

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.10.1</version>
  <configuration>
    <source>1.8</source>
    <target>1.8</target>
  </configuration>
</plugin>

If you are running a JDK that supports the release flag you can prefer that instead because it pins the standard library API to a specific Java release and avoids surprises when compiling on a newer JDK

<configuration>
  <release>8</release>
</configuration>

Annotation processors and compiler dependencies

Annotation processing and alternate compilers need to be visible to the compiler during the compile phase. You have two common options

• Put the processor artifact on the project dependencies with the provided scope or on the compile classpath when appropriate
• Declare processors inside the plugin configuration using annotationProcessorPaths so the compiler sees exactly what it needs

Example using annotationProcessorPaths which avoids polluting the main project classpath

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.10.1</version>
  <configuration>
    <release>8</release>
    <annotationProcessorPaths>
      <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.26</version>
      </path>
    </annotationProcessorPaths>
  </configuration>
</plugin>

When to add the processor under project dependencies

Some tools expect generated sources on the project classpath or need processor classes available at runtime during other plugin phases. In those cases add the annotation processor as a normal dependency and mark it provided if it should not be bundled into your final artifact.

Run the build and verify

After configuration run a clean compile and inspect the results

mvn clean compile

Check target/classes for compiled classes and target/generated-sources for any generated sources from annotation processing. Also run javac -version on your CI runner to make sure the JDK there supports the release option if you chose it.

Common pitfalls and smart tips

• Using source and target but compiling on a newer JDK may hide API mismatches. Prefer release when the JDK supports it
• If annotation processors are missing you will get missing symbol errors or absent generated classes at runtime
• Keep plugin versions explicit to avoid surprise upgrades from parent POMs or corporate BOMs

Follow these steps and your Maven plugin configuration will stop being the weakest link in your build chain. Your CI will thank you and your debugging sessions will drop in frequency which means more time for coffee or mild regret about architectural decisions.