Articles

Fix Java NoClassDefFoundError in Production and Tests (2026)

April 18, 2026 5 min read

The java.lang.NoClassDefFoundError happens when the Java Virtual Machine (JVM) loads a class at runtime and discovers that the class definition it expects to find is missing, even though the class was available during compilation. This isn’t a missing import; it’s a failure to locate the bytecode for a class that should be present.

Common Causes and Fixes

1. Missing JAR in Runtime Classpath: This is the most frequent culprit. The JVM looks for .class files and JARs containing them on the classpath. If the JAR containing the required class isn’t listed, you get this error.

  • Diagnosis:
    • Production: Use System.getProperty("java.class.path") in a running application or check your application server’s classpath configuration (e.g., catalina.properties for Tomcat, standalone.conf for WildFly).
    • Tests: Examine your build tool’s configuration for test dependencies (e.g., pom.xml for Maven, build.gradle for Gradle). For simple command-line execution, check the -cp or -classpath argument.
  • Fix:
    • Production: Add the missing JAR to the classpath. For a standalone JAR, this might look like: java -cp myapp.jar:lib/dependency1.jar:lib/dependency2.jar com.example.MainApplication. For application servers, add the JAR to the WEB-INF/lib directory of your WAR file or to the server’s shared library directory.
    • Tests: Ensure the JAR is declared as a test dependency. For Maven:
      <dependency>
    <groupId>com.example</groupId>
    <artifactId>my-library</artifactId>
    <version>1.0.0</version>
    <scope>test</scope> <!-- Or runtime, if needed -->
</dependency>
  • Why it works: The JVM now has a direct pointer to the location of the required .class file within the specified JAR.

2. Incorrect JAR Version: You might have a JAR on the classpath, but it’s an older version that doesn’t contain the class or method you’re trying to use. This is common with transitive dependencies.

  • Diagnosis:
    • Use mvn dependency:tree (Maven) or gradle dependencies (Gradle) to inspect the dependency tree and identify conflicting or older versions of a library.
    • Check the META-INF/MANIFEST.MF file inside the JARs for Implementation-Version or Bundle-Version attributes.
  • Fix:
    • Update the dependency to the correct version in your build file. For Maven, use <dependencyManagement> or explicitly exclude the older version and declare the newer one:
      <dependency>
    <groupId>com.example</groupId>
    <artifactId>my-library</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>com.example</groupId>
    <artifactId>another-dependency</artifactId>
    <version>1.5.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.example</groupId>
            <artifactId>my-library</artifactId> <!-- Exclude the transitive, older version -->
        </exclusion>
    </exclusions>
</dependency>
  • Why it works: The correct, newer version of the JAR is now present, containing the expected class definition.

3. Classpath Shading/Relocation Issues: When using build tools like Maven or Gradle, they might "shade" or relocate packages. If this process is misconfigured, or if multiple libraries include the same class with different shaded names, conflicts can arise.

  • Diagnosis:
    • Inspect the JARs themselves. Look for the expected class file. If you find it, check its package name. If the package name has been altered (e.g., com.google.common becoming shaded.org.apache.commons), that’s shading.
    • Use jar tvf your-app.jar | grep YourClass to see if YourClass exists and in what package.
  • Fix:
    • Review your build tool’s shading configuration. For Maven Shade Plugin, ensure relocations are correctly specified and that you’re not shading a class that should be left in its original package.
    • If two dependencies shade the same class to the same new name, you might need to exclude one of the conflicting dependencies or configure one to use a different shading prefix.
  • Why it works: Correct shading ensures that classes from different libraries don’t collide under the same package name, or that the intended version of a class is the one that ends up on the classpath.

4. Corrupted JAR Files: Less common, but a JAR file can become corrupted during download, transfer, or on disk.

  • Diagnosis:
    • Try to extract the .class file from the JAR using jar xf corrupted.jar com/example/MyClass.class. If this fails or produces corrupted output, the JAR is likely bad.
    • Re-download or re-build the artifact.
  • Fix:
    • Delete the corrupted JAR from your local Maven/Gradle cache (~/.m2/repository or ~/.gradle/caches) and let your build tool re-download it. If building from source, clean and rebuild the project artifact.
  • Why it works: A fresh, uncorrupted copy of the JAR ensures the integrity of the class definition.

5. Classloader Hierarchy Issues: In complex environments like application servers (Tomcat, JBoss/WildFly) or OSGi, multiple classloaders exist. A class might be loaded by one classloader, but the code trying to access it is using a different one, and the desired class isn’t visible to the latter.

  • Diagnosis:
    • Use a tool like jclarity or custom code to inspect the classloader hierarchy at runtime.
    • Check your application server’s deployment structure and classloader isolation policies. For example, Tomcat’s common/lib vs. webapp/WEB-INF/lib.
  • Fix:
    • Ensure the JAR containing the class is placed in a location accessible by the relevant classloader. Often, placing the JAR in the application’s WEB-INF/lib is sufficient. For shared libraries, use the server’s designated shared library directories.
    • Avoid using parent-first delegation if child-first is required for a specific dependency.
  • Why it works: Correct placement ensures the classloader that needs the class can find it, adhering to the JVM’s delegation model.

6. Initialization Failure: The NoClassDefFoundError can also occur if a class was found but failed during its static initialization. The JVM then prevents subsequent attempts to load that class.

  • Diagnosis:
    • Look for a preceding ExceptionInInitializerError. This is the key indicator. The stack trace of the ExceptionInInitializerError will show the root cause of the static initialization failure (e.g., an NPE in a static block, a malformed configuration file read during static init).
  • Fix:
    • Address the root cause of the ExceptionInInitializerError. This might involve fixing a bug in a static block, correcting a configuration file, or ensuring resources needed for initialization are available.
  • Why it works: By resolving the underlying issue that prevents successful static initialization, the class can be loaded and used without further errors.

The next error you’ll likely encounter after fixing NoClassDefFoundError is a ClassNotFoundException if the class is truly missing from the classpath entirely, or a NoSuchMethodError if the class is found but the specific method you’re calling doesn’t exist (often due to version mismatches).

Want structured learning?

Take the full Java course →