Skip to content
javahacks.dev
Debugging

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.

7 min read
Summarize in AI
Flat illustration of an editor window full of code, with the OpenJDK, Apache Maven and Gradle logos.

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:

src/main/java/dev/javahacks/debug/WhereFrom.javajava
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());
        }
    }
}
Shell
java -cp target/classes:target/lib/* dev.javahacks.debug.WhereFrom \
  org.slf4j.LoggerFactory com.fasterxml.jackson.databind.ObjectMapper java.sql.Connection
Text
org.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: null

If 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:

Shell
java -Xlog:class+load:file=classload.log -jar target/app.jar
grep 'org.slf4j.LoggerFactory' classload.log
Text
[1.204s][info][class,load] org.slf4j.LoggerFactory source: file:/app/lib/slf4j-api-1.7.36.jar

For 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:

Shell
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]}' | head
Text
org/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.jar

Two 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:

pom.xmlXML
<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:

java
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:

Shell
unzip -Z1 target/app.jar | grep '^BOOT-INF/lib/' | sort
Text
BOOT-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.jar

For a running process, jcmd shows the launch arguments and the classpath without a restart:

Shell
jcmd <pid> VM.command_line
jcmd <pid> VM.system_properties | grep java.class.path

Compare 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:

Text
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:

java
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:

Shell
java --module-path mods --describe-module com.acme.core
java --module-path mods --list-modules | grep acme

If 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.

  1. Read the full message, including Caused by. The first error is usually a symptom of a failed static initializer, not a missing class.
  2. Ask where the class came from with the probe or the class-load log.
  3. Compare that location to the version you expect, in the Maven or Gradle tree.
  4. Look for a duplicate, and check for a stale artifact in the deployment directory.
  5. 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.

Also inJava Core
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.