Debug Classpath Problems and Class Loading Failures in Java
Debug classpath problems in Java: find which jar a class came from, duplicate classes, version conflicts, class loaders and load logging.

NoClassDefFoundError, NoSuchMethodError, ClassCastException between two classes with the same name, and a library that behaves differently on the server than on your laptop. They have one root: the JVM loaded a class from somewhere other than where you thought, or loaded two copies, or could not see the one you meant. Reading the stack trace gets you the class name. It does not tell you which jar supplied it, and that is the question. This post gives you the tools to answer it in minutes: asking the JVM where a class came from, finding duplicate classes, listing the real runtime classpath, understanding the class loader hierarchy and checking the module path. Commands are for JDK 25 and apply to Spring Boot fat jars, application servers and plain java -cp launches.
Which jar did the class come from
When a method is missing at runtime that exists in your source, you are almost always running a different version of a library than you compiled against. Ask the JVM directly. A one-line probe works from any code that runs in the same JVM:
package dev.javahacks.debug;
public class WhereFrom {
public static void main(String[] args) throws Exception {
for (String name : args) {
Class<?> c = Class.forName(name);
var source = c.getProtectionDomain().getCodeSource();
System.out.println(name + " -> " + (source == null ? "bootstrap or JDK" : source.getLocation()));
System.out.println(" loader: " + c.getClassLoader());
}
}
}java -cp target/classes:target/lib/* dev.javahacks.debug.WhereFrom \
org.slf4j.LoggerFactory com.fasterxml.jackson.databind.ObjectMapper java.sql.Connectionorg.slf4j.LoggerFactory -> file:/app/lib/slf4j-api-1.7.36.jar
loader: jdk.internal.loader.ClassLoaders$AppClassLoader@2c13da15
com.fasterxml.jackson.databind.ObjectMapper -> file:/app/lib/jackson-databind-2.13.4.jar
loader: jdk.internal.loader.ClassLoaders$AppClassLoader@2c13da15
java.sql.Connection -> bootstrap or JDK
loader: nullIf the code expects SLF4J 2 and the line shows slf4j-api-1.7.36, you found it without reading a stack trace. For a class that cannot be loaded at all, you cannot call Class.forName; use the JVM's own log of every class load, which works without changing code:
java -Xlog:class+load:file=classload.log -jar target/app.jar
grep 'org.slf4j.LoggerFactory' classload.log[1.204s][info][class,load] org.slf4j.LoggerFactory source: file:/app/lib/slf4j-api-1.7.36.jarFor a class that was never found, -verbose:class or this log shows the last class that did load before the failure, and the absence of the line you wanted. The -Xlog options are documented in the java command reference. The classic error messages and their causes are in ClassNotFoundException versus NoClassDefFoundError.
Duplicate classes
Two jars on the classpath that contain the same class are the nastiest case, because the JVM silently uses the first one it finds, and the first one depends on classpath order. A shaded or fat jar that bundles its dependencies is a common source, as is a library published under two artifact names.
Find them with a short script before you suspect anything else. This lists every class that appears in more than one jar of a directory:
for j in lib/*.jar; do
unzip -Z1 "$j" '*.class' | sed "s|\$| $(basename "$j")|"
done | sort | awk '{c[$1]=c[$1]" "$2; n[$1]++} END {for (k in n) if (n[k]>1) print k":"c[k]}' | headorg/apache/commons/logging/Log.class: commons-logging-1.2.jar spring-jcl-6.1.4.jar
javax/servlet/Filter.class: servlet-api-2.5.jar tomcat-embed-core-9.0.60.jarTwo interesting hits already: a logging facade that two jars both provide, and a servlet API duplicated, which is the exact trap behind the namespace errors in javax to jakarta ClassNotFoundException. In Maven, make the build refuse duplicates permanently with the enforcer plugin's extra rules:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.5.0</version>
<dependencies>
<dependency>
<groupId>org.codehaus.mojo</groupId>
<artifactId>extra-enforcer-rules</artifactId>
<version>1.9.0</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>no-duplicate-classes</id>
<goals><goal>enforce</goal></goals>
<configuration>
<rules>
<banDuplicateClasses>
<findAllDuplicates>true</findAllDuplicates>
</banDuplicateClasses>
</rules>
</configuration>
</execution>
</executions>
</plugin>The usual fix is to exclude one of the two artifacts, pin the version in dependencyManagement, or switch to the single artifact that replaces both. The workflow for a conflict you found in the tree is in fixing Maven dependency conflicts with the tree.
What is on the classpath at runtime
The build file says what you asked for; the running process has what the launcher assembled. Print it from the inside:
System.out.println(System.getProperty("java.class.path"));For a Spring Boot fat jar that prints only the launcher, since the dependencies live in BOOT-INF/lib and are loaded by a custom class loader. Extract the list instead:
unzip -Z1 target/app.jar | grep '^BOOT-INF/lib/' | sortBOOT-INF/lib/jackson-databind-2.19.1.jar
BOOT-INF/lib/slf4j-api-2.0.17.jar
BOOT-INF/lib/spring-core-7.0.0.jarFor a running process, jcmd shows the launch arguments and the classpath without a restart:
jcmd <pid> VM.command_line
jcmd <pid> VM.system_properties | grep java.class.pathCompare this with the Maven tree. A difference means a plugin, a profile or a Dockerfile changed what was copied: a stale jar left in a lib directory from the last build is the most common cause, and clean is the cheapest fix.
Class loader hierarchy
Java loads classes through a chain: the bootstrap loader (the JDK's own classes), the platform loader, the application loader, and then any custom loaders an application server or framework adds. A loader first asks its parent, and only loads the class itself if the parent could not. Two consequences explain a lot of strange behavior.
The same class name in two loaders is two different classes. ClassCastException: class com.acme.Plugin cannot be cast to class com.acme.Plugin is not a typo. The two have the same name and different loaders, so the JVM treats them as unrelated types. The message names the loaders when you read it in full:
java.lang.ClassCastException: class com.acme.Plugin cannot be cast to class com.acme.Plugin (com.acme.Plugin is in unnamed module of loader 'app'; com.acme.Plugin is in unnamed module of loader com.acme.PluginLoader @4e50df2e)This is routine with plugin systems, hot reload (Spring DevTools uses a restart class loader on purpose) and application servers. The fix is to make the shared interface load from the common parent and only the implementation from the child.
Child-first loading. Web containers load a web application's classes before the parent's for most packages, so a jar in WEB-INF/lib can shadow one in the server. That is useful and also how a duplicate sneaks in. Print the chain from any class to see where yours sits:
for (ClassLoader l = MyClass.class.getClassLoader(); l != null; l = l.getParent()) {
System.out.println(l);
}For a live process, jcmd <pid> VM.classloader_stats lists loaders and how many classes each loaded, and a surprising number of loaders with similar names is a loader leak (every redeploy adds one that never goes away). The API is in the ClassLoader Javadoc.
Module path
Code launched with --module-path instead of -cp follows different rules. A package that appears in two modules is an error at startup (Module X and module Y export package P to module Z), strongly encapsulated JDK internals are refused with InaccessibleObjectException, and an automatic module's name is derived from the jar's file name unless the manifest says otherwise. Check what the runtime resolved:
java --module-path mods --describe-module com.acme.core
java --module-path mods --list-modules | grep acmeIf you need to open a package for a library that reflects into it, the flag is --add-opens java.base/java.lang=ALL-UNNAMED, which is a workaround and a note to upgrade the library. Most Spring and Jakarta applications run on the classpath and never meet this layer.
Workflow
When a class-loading error arrives, take the same five steps every time.
- Read the full message, including
Caused by. The first error is usually a symptom of a failed static initializer, not a missing class. - Ask where the class came from with the probe or the class-load log.
- Compare that location to the version you expect, in the Maven or Gradle tree.
- Look for a duplicate, and check for a stale artifact in the deployment directory.
- If two loaders are involved, draw the chain and put the shared types in the parent.
A slow start is sometimes caused by the same scanning, and the method for that is in debugging slow Java startup.
Where this does not apply
If the error is UnsupportedClassVersionError, the class was found and is too new for the running JVM, so check the Java versions instead of the classpath. If a class is present and fails during initialization, the stack trace of the ExceptionInInitializerError is the thing to read. And in a native image there is no class loading at runtime, so a missing class there is a registration problem at build time.


