The java.lang.NoClassDefFoundError in JUnit

1. Overview

In this article, we'll understand why the java.lang.NoClassDefFoundError occurs in JUnit and how to fix it. This issue is mainly related to IDE's configurations. Therefore, we'll be focusing on the most popular IDEs: Visual Studio Code, Eclipse, and IntelliJ to reproduce and resolve this error.

2. What is java.lang.NoClassDefFoundError?

When the Java Runtime runs a Java program, it does not load all the classes and dependencies at once. Instead, it calls upon the Java Classloader to load classes in memory as-and-when-required. While loading a class, if the Classloader cannot find the class's definition, it throws the  NoClassDefFoundError.

There are a couple of reasons for which Java cannot find the class's definition, which are:

• Missing a few dependent jars which is the most common reason.
• All jars are added as dependencies but in the wrong path.
• Version mismatches in the dependencies.

3. VS Code

For writing Junit4 test cases, we require the Junit4 jar. However, the Junit4 has an internal dependency on the hamcrest-core jar.

If we miss adding the hamcrest-core jar as a dependency in our classpath, Java throws the NoClassDefFoundError. The classpath is as follows:

One other scenario is when we added both the jars, but the versions don't match. For example, if we have added JUnit jar version 4.13.2 and the hamcrest-core jar version 2.2, the NoClassDefFoundError is thrown:

In both cases, the same stack trace is printed:

java.lang.NoClassDefFoundError: org/hamcrest/SelfDescribing
	at java.base/java.lang.ClassLoader.defineClass1(Native Method)
	at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1010)
	at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150)
	at java.base/jdk.internal.loader.BuiltinClassLoader.defineClass(BuiltinClassLoader.java:855)
	at java.base/jdk.internal.loader.BuiltinClassLoader.findClassOnClassPathOrNull(BuiltinClassLoader.java:753)
	at java.base/jdk.internal.loader.BuiltinClassLoader.loadClassOrNull(BuiltinClassLoader.java:676) ...

To resolve the error in both the scenarios (missing dependencies and version mismatch), we need to add the correct dependencies. The correct dependencies in the case of Junit4 are junit-4.13.2.jar and hamcrest-core-1.3.jar. Adding these two jars in the dependencies (Referenced Libraries) resolves the error. The instructions to add and remove external jars in VS Code are present here. Our referenced library section should be set up as:

4. Eclipse

In Eclipse IDE that supports Java 9 and above, we have a classpath and a module path. To resolve module dependency, we use the module path. However, adding external jars in the module path does not make them available for the class loader. Hence the class loader considers them as missing dependencies and throws the NoClassDefFoundError.

Hence if our dependency looks like the below image, running a Junit test case results in a NoClassDefFoundError:

The stack trace generated on running the JUnit test is:

java.lang.NoClassDefFoundError: org/junit/runner/manipulation/Filter
	at java.base/java.lang.Class.forName0(Native Method)
	at java.base/java.lang.Class.forName(Class.java:377)
	at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.loadTestLoaderClass(RemoteTestRunner.java:381)

In Eclipse, we need to add the jars under the classpath and not in the module path. So, to add external jars correctly, follow the path:

right-click on the Project -> Build Path -> Configure Build Path

In the window that opens, remove the jars from under the module path and add them under the classpath. This resolves the NoClassDefFoundError. The correct classpath for running JUnit should be similar to:

5. IntelliJ

Running JUnit 5 test cases requires both the Jupiter engine and Jupiter API. The Jupiter engine is internally dependent on the Jupiter API, and hence most of the time,  it is sufficient to add just the Jupiter engine dependency in the pom.xml. However, Adding only the Jupiter API dependency in our pom.xml and missing the Jupiter engine dependency results in the NoClassDefFoundError.

The incorrect setup in the pom.xml would be like this:

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>5.4.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Running a simple test case with this setup results in the following stack trace:

Exception in thread "main" java.lang.NoClassDefFoundError: org/junit/platform/engine/TestDescriptor
	at java.base/java.lang.Class.forName0(Native Method)
	at java.base/java.lang.Class.forName(Class.java:375)
	at com.intellij.rt.junit.JUnitStarter.getAgentClass(JUnitStarter.java:230)
....

In IntelliJ, to correct the dependencies, we need to correct the pom.xml. The corrected pom.xml looks like this:

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>5.4.2</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>5.4.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Alternatively, we can add junit-jupiter-engine since adding it automatically adds the junit-jupiter-api jar to the classpath and resolves the error.

6. Summary

In this article, we saw different reasons for the java.lang.NoClassDefFoundError to occur in JUnit. We also saw how we resolve the error in different IDEs. The entire code for this tutorial is available over on GitHub.