JaCoCo "Error while instrumenting class" / mismatch in CI

JaCoCo matches execution data to class files by a content id. When the .class files passed to the report differ from the ones that ran (different compiler, stale target, duplicate class on the path), it fails to instrument or aborts the report.

What this error means

The build fails with "Error while instrumenting class X" or "Can't add different class with same name" during report generation, often after a Java/compiler change or a stale build dir.

JaCoCo

[ERROR] Failed to execute goal org.jacoco:jacoco-maven-plugin:0.8.12:report (report)
on project my-app: Error while creating report: Can't add different class with same name: com/example/App

Common causes

Class files do not match the executed bytecode

A stale target/classes, or compiling with a newer Java than JaCoCo supports, produces class ids that do not match the exec data.

Duplicate classes with the same name on the path

A shaded/relocated jar or a duplicated class file makes JaCoCo see two different definitions of the same class name.

How to fix it

Clean build with a supported Java

Run a clean build so class files match what ran.
Use a JaCoCo version that supports your Java bytecode level.
Re-run report generation from the fresh build output.

Terminal

mvn clean verify   # rebuild classes so they match the exec data

Upgrade JaCoCo for newer Java

Newer Java releases need a newer JaCoCo; pin a version that supports your target bytecode.

pom.xml

<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.12</version>
</plugin>

How to prevent it

Run clean before coverage so class files are not stale.
Keep JaCoCo current with the Java version you compile against.
Avoid duplicate class definitions from shaded jars on the report path.