Resolving NoSuchMethodError Caused by Duplicate Classes with Different Method Signatures in Java Projects

Phenomenon

In the project, two different business JARs both contain a class with the same name and package, and the methods are almost identical, but one class has a method whose return type differs, resulting in a different method signature. At runtime this causes a java.lang.NoSuchMethodError exception.

The duplicated class originates from copied code; after a business change, one JAR upgraded the return type of that method, altering the signature.

Cause

We first review class‑loading concepts. Java uses a parent‑delegation model: when a class is requested, the current class loader first delegates the request to its parent; only if the parent cannot load the class does the loader attempt to load it itself.

Different class loaders load classes from different paths. If the same‑named class and method exist in two JARs located in distinct file‑system locations, they may be loaded by different class loaders, and the parent‑child relationship determines which version is used. If they are loaded by the same class loader, the first‑found rule usually applies, though exact behavior depends on the loader implementation.

Avoidance

Having identical classes and methods in different JARs can cause runtime exceptions; this should be avoided. Automated detection can be achieved with the Maven Enforcer‑rules plugin combined with the Extra Enforcer Rules banDuplicateClasses rule.

Summary

When identical classes and methods exist in different JARs, Java's class‑loading mechanism determines which version is used based on loading order; incompatibilities between duplicated classes lead to runtime errors such as NoSuchMethodError .