How to Diagnose and Fix Maven Dependency Conflicts (NoSuchMethodError & ClassNotFoundException)

Why conflicts happen

When a project depends on two libraries (A and B) that each require a different version of the same transitive dependency (e.g., Guava 30.0 vs. Guava 31.0), Maven selects only one version, which can break one of the libraries.

Common errors

NoSuchMethodError

Occurs when the runtime class version differs from the compile‑time version, and a method expected in a newer version is missing in the older one.

ClassNotFoundException

Occurs when a required class is not present because the dependency was excluded or never introduced.

Investigation steps

Run mvn dependency:tree to display the full hierarchy of dependencies.

If the tree is long, filter for a specific artifact, e.g., mvn dependency:tree -Dincludes=com.google.guava.

Use the verbose flag to see omitted dependencies: mvn dependency:tree -Dverbose. The output highlights which module brings which version.

Example output shows a conflict where Guava 30.0 is selected while Guava 31.0 is omitted.

Resolution methods

Method 1: Exclude the transitive dependency

<dependency>
  <groupId>com.example</groupId>
  <artifactId>lib-a</artifactId>
  <version>1.0</version>
  <exclusions>
    <exclusion>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Method 2: Force a specific version by declaring it directly

<!-- Force Guava 31.0-jre -->
<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>31.0-jre</version>
</dependency>

Method 3: Use dependencyManagement to set a unified version

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>31.0-jre</version>
    </dependency>
  </dependencies>
</dependencyManagement>

All modules inherit the specified version.

Typical conflict cases

Case 1: Logging framework clash

SLF4J: Class path contains multiple SLF4J bindings.

Solution: exclude one of the conflicting logging implementations (e.g., slf4j-log4j12).

Case 2: Jackson version mismatch

Solution: import a Jackson BOM via dependencyManagement to align versions.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson</groupId>
      <artifactId>jackson-bom</artifactId>
      <version>2.15.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

IDEA plugin assistance

Open pom.xml in IntelliJ.

Click the Dependency Analyzer at the bottom of the window.

Red entries indicate conflicting dependencies.

Right‑click a red entry to exclude it directly.

Prevention

1. Use a BOM to manage versions

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.2.0</version>
</parent>

2. Regularly analyze dependencies

mvn dependency:analyze

This command reports unused declared dependencies and used but undeclared ones.

When local works but server fails

Check which JAR version is actually loaded on the server or inspect class‑loading output.

# Show the Guava JAR present on the server
cd /app/lib
ls -la | grep guava

# Verbose class loading to see which version is used
java -verbose:class -jar app.jar | grep guava

Summary

Identify the conflict with mvn dependency:tree -Dincludes=....

Determine the required version.

Resolve by excluding the transitive dependency, declaring the desired version, or using dependencyManagement (BOM).

Verify the fix with mvn dependency:tree.

Using a BOM to manage versions prevents most dependency conflicts.