How to Resolve the NoClassDefFoundError in Java

The NoClassDefFoundError is a runtime error in Java that occurs if the Java Virtual Machine (JVM) or a ClassLoader instance attempts to load the definition of a class but cannot find it at runtime. The class definition exists at compile-time but is not available at runtime.

To explain using an analogy, it's like preparing a parcel for collection by a courier but when the courier arrives, they can't find the parcel because the directions to its location are missing. The JVM, like the courier, looks for the class definition (parcel) in the classpath (directions). If the class is not found where expected, the JVM throws a NoClassDefFoundError.

What Causes NoClassDefFoundError

The NoClassDefFoundError occurs in Java when the JVM is unable to find a particular class at runtime which was available at compile-time.

Common causes of the class definition being unavailable at runtime are:

Missing JAR file
Permission issues
Incorrect classpath at runtime

This can happen as part of a normal method call or when creating an instance of the class using the new expression. Therefore, it can occur during the linking or loading of the unavailable class.

NoClassDefFoundError Example

Here’s an example of a NoClassDefFoundError thrown when a class is attempted to be loaded that is available at compile-time but not at runtime:

class Vehicle {
    private String make;

    public String getMake() {
        return make;
    }

    public void setMake(String make) {
        this.make = make;
    }
}

public class NoClassDefFoundErrorExample {
    public static void main(String args[]) {
        Vehicle vehicle = new Vehicle();
        vehicle.setMake("Audi");
        System.out.println("Make = " + vehicle.getMake());
    }
}

In the above example, an instance of the Vehicle class is created in the NoClassDefFoundErrorExample.main() method and one of its methods is called. When the NoClassDefFoundErrorExample class is compiled and executed using the command line, it works fine and produces the correct output as expected:

$ javac NoClassDefFoundErrorExample.java 
$ ls
NoClassDefFoundErrorExample.class   Vehicle.class
NoClassDefFoundErrorExample.java
$ java NoClassDefFoundErrorExample
Make = Audi

Now, if the Vehicle.class file is renamed and the NoClassDefFoundErrorExample class is executed again without recompiling, the NoClassDefFoundError is thrown:

$ mv Vehicle.class Vehicle2.class 
$ ls
NoClassDefFoundErrorExample.class   Vehicle2.class
NoClassDefFoundErrorExample.java
$ java NoClassDefFoundErrorExample
Exception in thread "main" java.lang.NoClassDefFoundError: Vehicle
    at NoClassDefFoundErrorExample.main(NoClassDefFoundErrorExample.java:15)
Caused by: java.lang.ClassNotFoundException: Vehicle
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:602)
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:178)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:522)
    ... 1 more

How to Resolve NoClassDefFoundError

The following steps should be followed to resolve a NoClassDefFoundError in Java:

Ensure the JAR file containing the missing class is present in the classpath. The most common reason for the NoClassDefFoundError is that a particular class is not available in the application classpath. Find out which JAR file contains the problematic class and check whether this JAR is present in the application classpath. If not, the JAR should be added to the classpath and the application should be recompiled and executed again.
Ensure classpath is not overridden. If that JAR is already present in the classpath, make sure the classpath is not overridden (e.g. by a start-up script). After finding out the exact classpath used by the application, the JAR file should be added to it.
Check the manifest file. Ensure that the unavailable class is not defined in the Class-Path attribute. If so, it should be defined.
Check for failures of static initialization. The NoClassDefFoundError can also occur due to the failure of static initialization. Check for the java.lang.ExceptionInInitializerError in the application logs.

The earlier example can be updated to resolve the error by recompiling the class:

$ javac NoClassDefFoundErrorExample.java 
$ ls
NoClassDefFoundErrorExample.class   Vehicle.class
NoClassDefFoundErrorExample.java        Vehicle2.class

Here, the NoClassDefFoundErrorExample class is recompiled and the Vehicle.class file is generated again. Since the required class definition can now be found at runtime, when the NoClassDefFoundErrorExample class is executed again, it works correctly and produces the correct output as expected:

$ java NoClassDefFoundErrorExample
Make = Audi

Track, Analyze and Manage Errors With Rollbar

Managing errors and exceptions in your code is challenging. It can make deploying production code an unnerving experience. Being able to track, analyze, and manage errors in real-time can help you to proceed with more confidence. Rollbar automates error monitoring and triaging, making fixing Java errors easier than ever. Try it today!