Fix ClassNotFoundException and NoClassDefFoundError
Tell ClassNotFoundException from NoClassDefFoundError, then find the missing jar, the wrong scope or the failed static initializer behind each.

Two exceptions send Java developers searching for the same thing, a missing class, and they are not the same failure:
java.lang.ClassNotFoundException: com.acme.MissingException in thread "main" java.lang.NoClassDefFoundError: Helper
at App.main(App.java:3)
Caused by: java.lang.ClassNotFoundException: HelperClassNotFoundException is an exception your code or a library asked for: someone called Class.forName, ClassLoader.loadClass or a reflection-based framework tried to load a class by name and it was not found. NoClassDefFoundError is an error the JVM throws on its own, when a class that was present when the code was compiled cannot be found or initialized now, at the moment your running code first needs it. Reading the second line, the Caused by, usually tells you which of five situations you are in. This post reproduces both with real output, explains the difference, and walks the causes: a dependency that is not packaged, code that works in the IDE and not from the command line, a static initializer that failed, two versions of one library and class loader boundaries. Output below was produced by running the code on JDK 17.
The difference, shown
Compile a program that depends on a second class, run it, then delete the second class's file and run it again:
public class App {
public static void main(String[] args) throws Exception {
try {
Class.forName("com.acme.Missing");
} catch (ClassNotFoundException e) {
System.out.println("CNFE: " + e);
}
System.out.println(Helper.hi());
}
}public class Helper {
public static String hi() {
return "hello";
}
}javac *.java
java App
rm Helper.class
java AppCNFE: java.lang.ClassNotFoundException: com.acme.Missing
hello
CNFE: java.lang.ClassNotFoundException: com.acme.Missing
Exception in thread "main" java.lang.NoClassDefFoundError: Helper
at App.main(App.java:3)
Caused by: java.lang.ClassNotFoundException: HelperOn the first run Helper was found. The explicit Class.forName("com.acme.Missing") throws ClassNotFoundException on both runs, because that class never existed, and the code expects and catches it. On the second run, the line Helper.hi() compiled fine, since Helper existed at compile time. At runtime the JVM could not locate it, so it threw NoClassDefFoundError, with the original ClassNotFoundException as the cause. The rule that follows:
ClassNotFoundException | NoClassDefFoundError | |
|---|---|---|
| Kind | Checked exception | Error (a LinkageError) |
| Thrown when | Code explicitly loads a class by name | The JVM needs a class it compiled against |
| Typical origin | Class.forName, reflection, JDBC drivers, frameworks | A normal new, a method call or a field access |
| Means | The name is not on the classpath | The class was there at build time, not at run time (or failed to initialize) |
Both mean the same underlying thing in most cases, the classpath at runtime differs from the classpath at compile time, and both are fixed by making them agree. The Javadoc for each is at ClassNotFoundException and NoClassDefFoundError.
Cause 1: the dependency is not packaged
The most common reason: the library is on the compile classpath and not in what you run. In Maven, a provided or test scope compiles but does not ship. Check what actually landed in the artifact:
unzip -l target/shop.jar | grep -i 'commons-lang3'(no output)No line means the library is not in the jar, and the first call into it fails. In a Spring Boot executable jar the libraries live under BOOT-INF/lib, so grep for that path. Compare with the build's view:
mvn -B dependency:tree -Dincludes=org.apache.commons:commons-lang3[INFO] \- org.apache.commons:commons-lang3:jar:3.17.0:providedThe scope provided is the answer: the build assumed the runtime supplies it, and nothing does. Change it to compile (the default) or runtime. The scopes and what each includes are in Maven dependency scopes with examples. In Gradle, compileOnly has the same effect and implementation is the shipping scope. If you build a thin jar and run it with java -jar, the libraries must be listed in the manifest Class-Path or on -cp; a plain jar plugin build does not bundle dependencies. A server that is meant to provide the library (a servlet API in Tomcat) is the legitimate use of provided.
Cause 2: it works in the IDE and fails from the command line
The IDE builds its own classpath from the project model, which may include things your build file does not (test-scoped jars on the run configuration, a module added manually, output directories). The packaged application has only what the build put in. The symptom is a program that runs fine from the IDE's run button and fails with NoClassDefFoundError from java -jar. Reproduce the real runtime classpath outside the IDE, from the build:
mvn -B clean package
java -jar target/shop.jarIf that fails and the IDE run works, the IDE's classpath is the more generous one, and the build file is missing a dependency (or has it in the wrong scope). Re-import the project after changing build files, or the IDE keeps an outdated model, which gives the reverse mismatch. Running the same command that production runs is the only reliable test; add it to CI so the failure is caught on the branch.
Cause 3: a static initializer failed
A NoClassDefFoundError with the message Could not initialize class X does not mean the class file is missing. It means the class was found, its static initialization threw an exception earlier, and the JVM marked it unusable. The first failure produces ExceptionInInitializerError; every use afterward produces NoClassDefFoundError:
static class Broken {
static final int N = Integer.parseInt("not a number");
}java.lang.ExceptionInInitializerError: null
java.lang.NoClassDefFoundError: Could not initialize class Init$BrokenThe second message is what shows up in logs, often hours after the first, and it is misleading: nothing is missing. Search the logs backward for the first ExceptionInInitializerError and read its Caused by, which names the real problem: a missing configuration value read in a static block, a database connection opened in a static field, a resource not found. The cure is to move failure-prone work out of static initializers into explicit code that reports errors, and to read the earlier error. The ordering rules that make this happen are in constructors and initialization order, and the raw mechanics of loading and linking are in how the JVM runs bytecode.
Cause 4: two versions of the same library
The class exists, in the wrong version. Your code was compiled against version 2, and the runtime loaded version 1, which lacks the class or the method you call. The related error is NoSuchMethodError or NoSuchFieldError, and for a class that exists in only one of the versions, NoClassDefFoundError. Find the versions in play:
mvn -B dependency:tree -Dverbose -Dincludes=com.google.guava[INFO] +- com.acme:report-engine:jar:4.2:compile
[INFO] | \- com.google.guava:guava:jar:19.0:compile
[INFO] \- com.google.guava:guava:jar:33.0.0-jre:compileThe second line is the winner Maven picked by the nearest-wins rule, and the first is what report-engine was built against. If your code or a library calls a method that exists only in the version that lost, the runtime error follows. The mediation rules and how to override them are in Maven dependency mediation. Pin the version in dependencyManagement, exclude the old one, and rebuild. A different version problem is a class compiled for a newer Java than the one running it, which gives UnsupportedClassVersionError, described in UnsupportedClassVersionError. After a Jakarta EE upgrade, the mirror case with javax and jakarta packages is in fixing javax to jakarta ClassNotFoundException.
Cause 5: the module system or a class loader boundary
The class is on the classpath and still not visible from where the request is made. Two situations.
Class loader hierarchy. In an application server or a plugin system, each application or plugin has its own class loader. A loader sees its own classes and its parent's, never a sibling's. A library jar in one web application's WEB-INF/lib is invisible to another, and a class in the server's shared directory cannot see classes from inside a deployed application. Code in a shared library that tries to load an application class by name (Class.forName(name)) uses the library's loader, which cannot see it, and throws ClassNotFoundException. The fix is to load with the right loader: Class.forName(name, true, Thread.currentThread().getContextClassLoader()), which is why many frameworks use the context class loader.
Java modules. On the module path, a package must be exported and read. A class that exists in a module that is not required, or in a package that is not exported to the caller, fails at access time with IllegalAccessError or, for reflective loads, with ClassNotFoundException. Add the missing requires or exports, or --add-modules and --add-opens flags on the command line for legacy libraries.
See what the JVM loaded
When the above does not settle it, ask the JVM, not the build. Log every class load and look for the class, or the last one before the failure:
java -Xlog:class+load:file=classload.log -jar target/shop.jar
grep -n 'org.apache.commons.lang3.StringUtils' classload.log812:[0.944s][info][class,load] org.apache.commons.lang3.StringUtils source: jar:file:/app/lib/commons-lang3-3.12.0.jar!/The source: shows which jar supplied it, so a version surprise is visible immediately. If the class never appears in the log, it was never found. Inside a running program, Class.forName("x.Y").getProtectionDomain().getCodeSource() gives the same answer. The full toolkit, including finding duplicate classes across jars and walking the loader chain, is in debugging classpath and class loading problems. The related process for a program that is slow to start for the same reason is separate.
Where this does not apply
If the class name in the message is a framework-generated proxy (Foo$$SpringCGLIB$$0), the problem is a proxy generation failure, and the cause is in the Caused by. If the message names a class from your own code that you just renamed, you have a stale build: run a clean build. If a native image reports the error, the class was not registered for reflection at build time, which is a different fix with its own tooling. And when the error appears only on one machine of several, compare the deployed artifacts byte for byte; a partial deployment is more common than it should be.


