java.lang.NoClassDefFoundError Problem patterns

Getting a java.lang.NoClassDefFoundError when supporting a Java EE application is quite common and at the same time complicated to resolve.

The article will provide you with the common problem patterns responsible for java.lang.NoClassDefFoundError problems.

I’m also working on a real life case study on this subject which I will make available shortly from this Blog.

java.lang.NoClassDefFoundError– what is it?

This runtime error is thrown by the JVM when it tries to load the definition of a Class and when such Class definition could not be found in the current Class loader tree.

This normally means that the compiled version of the reference to this Class was done successfully but that such reference at runtime can not be found.

Sound confusing? Let’s have a look at the visual diagram below so you can better understand this fundamental problem.

Now if you are interested, find below the source code of our sample program along with java.lang.NoClassDefFoundError error.

// ClassA.java

 

package com.cgi.tools.java;

public class ClassA {

     private ClassB instanceB = null;

     private ClassC instanceC = null;

    

     public ClassA() {

           instanceB = new ClassB();

           instanceC = new ClassC();

     }

}

// ClassB.java

package com.cgi.tools.java;

public class ClassB {

}

// ClassC.java

package com.cgi.tools.java;

public class ClassC {

}

// ProgramA.java

package com.cgi.tools.java;

public class ProgramA {

     /**

      * @param args

      */

     public static void main(String[] args) {

          

           try {

                ClassA instanceA = new ClassA();

               

                System.out.println("ClassA instance created properly!");

           }

           catch (Throwable any) {

                System.out.println("Unexpected problem! "+any.getMessage()+" ["+any+"]");

           }   

     }

}

## ProgramA runtime classpath and output – with ClassC.jar

java -classpath ClassA.jar;ClassB.jar;ClassC.jar;ProgramA.jar com.cgi.tools.java.ProgramA

ClassA instance created properly!

## ProgramA runtime classpath and output – without ClassC.jar

// We voluntarily omitted to add ClassC.jar in the System classpath

java -classpath ClassA.jar;ClassB.jar;ProgramA.jar com.cgi.tools.java.ProgramA

Unexpected problem! com/cgi/tools/java/ClassC

[java.lang.NoClassDefFoundError: com/cgi/tools/java/ClassC]

What are the most common scenarios causing NoClassDefFoundError?

There are a few common scenarios which can lead to NoClassDefFoundError in your Java EE environment or standalone Java program.

# Problem pattern #1 – Missing vendor or third party library in System classpath or Java EE App classloader

A missing Java library of your Java EE server itself (Weblogic, WAS, JBoss etc.) or third party (Apache, Spring, Hibernate etc.) is the most common program; exactly like our above sample program.

# Solution

Resolution requires proper root cause analysis as per below recommended steps:

1)       Review the NoClassDefFoundError error and identify the missing Java Class

2)       Search through your local development and / or build environment and identify which Jar file contains the missing Java Class

3)       Once jar file(s) is / are identified, compare your local / build classpath with your production / problematic environment

4)       Resolution may include adding the missing JAR file(s) to the System class path or to your application EAR file for example

# Problem pattern #2 - Vendor or third party library version mismatch in System classpath or Java EE App classloader

This problem pattern is less common but trickier to pinpoint the root cause. This is a normally caused by using wrong version of a shared third party library like Apache commons logging etc.

# Solution

The resolution is quite similar to pattern #1:

1)       Review the NoClassDefFoundError error and identify the missing Java Class along with the referrer (very important)

2)       Search through your local development and / or build environment and identify which Jar file contains the missing Java Class

3)       Search through your local development and / or build environment and identify which Jar file contains the referrer Java Class

4)       Once jar file(s) is / are identified, compare your local / build classpath with your production / problematic environment

5)       Resolution may include replacing the problematic JAR file(s) with the right version as per the third party API documentation; this might include replacement of the JAR file referrer depending on your root cause analysis results

# Problem pattern #3 – static{} block code failure

This problem pattern is also quite common and can take some time to pinpoint. Java offers the capability to write some code to be executed once in life time of the JVM / Class loader. This is achieved via a static{} block, called static initializer, normally located right after the class instance variables.

Unfortunately, proper error handling and “non happy paths” for static initializer code blocks are often overlooked which opens the door for problems.

Any failure such as an uncaught Exception will prevent such Java class to be loaded to its class loader.  The pattern is as per below:

·         the first attempt to load the class will generate a java.lang.ExceptionInInitializerError; preventing the class loader to load the referenced class

·         subsequent calls will then generate a java.lang.NoClassDefFoundError from any other referencing classes in a consistent manner until the problem is resolved and the JVM restarted (or live redeploy via your Java EE server redeploy task)

# Solution

Resolution requires proper root cause analysis as per below recommended steps:

1)       Review the NoClassDefFoundError error and identify the affected Java Class

2)       Perform a code review of the affected Java class and see if any static{} initializer block can be found

3)       If found, review the error handling and add proper try{} catch{} along with proper logging in order to understand the root cause of the static block code failure

4)       Compile, redeploy, retest and confirm problem resolution

Final words

I hope this article has helped you better understand under which condition the JVM is throwing a NoClassDefFoundError error and the common causes.

If you still have any doubt, please feel free to add a comment or question if you are still struggling to identify the root cause of your NoClassDefFoundError problem.

Posted in: NoClassDefFoundError Patterns