3 ways to solve java.lang.NoClassDefFoundError in Java J2EE

I know how frustrating is to see "Exception in thread "main" java.lang.NoClassDefFoundError" while running your Java application. This is one of the dreaded problem in Java  which is also a manifestation of NoClassDefFoundError in Java. I have seen it a couple of times and spent quite a lot of time initially to figure out what is wrong, which class is missing etc. The first mistake I did was mingling java.lang.ClassNotfoundException and NoClassDefFoundError, in reality, are totally different, and my second mistake was using the trial and error method to solve this java.lang.NoClassDefFoundError instead of understanding why NoClassDefFoundError is coming, what is the real reason behind NoClassDefFoundError and how to resolve this.

In this Java tutorial, I have tried to rectify that mistakes and uncover some secrets of NoClassDefFoundError in Java and will share my experience around it. NoClassDefFoundError is not something that cannot be resolved or is hard to resolve it’s just its manifestation that puzzles most Java developers. 

This is the most common error in Java development along with java.lang.OutOfMemoroyError: Java heap space and java.lang.OutOfMemoryError: PermGen space  Anyway lets see Why NoClassDefFoundError comes in Java and what to do to resolve NoClassDefFoundError in Java.

What is the reason for NoClassDefFoundError in Java?

NoClassDefFoundError in Java comes when Java Virtual Machine is not able to find a particular class at runtime which was available at compile time. 

For example, if we have a method call from a class or accessing any static member of a class and that class is not available during run-time then JVM will throw NoClassDefFoundError. 

It’s important to understand that this is different than ClassNotFoundException which comes while trying to load a class at run-time only and the name was provided during runtime, not at compile-time. Many Java developer mingles this two Error and gets confused.

In short, NoClassDefFoundError will come if a class was present during compile time but not available in java classpath during runtime. Normally you will see the below line in the log when you get NoClassDefFoundError:

Exception in thread "main" java.lang.NoClassDefFoundError

Exception in thread “main” simply indicates that it's the “main” thread that is not able to find a particular class it could be any thread so just don’t worry. The difference between this error coming in the main thread and another thread is when Exception in thread “main” comes program crashes or shut itself down as opposed to other thread in which case your program will continue to run. 

If you are really curious and think that you understand how class loading works, I suggest you try some puzzles from Joshua Bloch's Java Puzzlers, it has got some really tricky questions to test your knowledge.

Difference between java.lang.NoClassDefFoundError and ClassNotFoundException in Java

Many times we confused ourselves with java.lang.ClassNotFoundException and java.lang.NoClassDefFoundError, though both of them are related to Java Classpath they are completely different from each other. 

ClassNotFoundException comes when JVM tries to load a class at runtime dynamically means you give the name of the class at runtime and then JVM tries to load it and if that class is not found in the classpath it throws java.lang.ClassNotFoundException. 

While in the case of NoClassDefFoundError the problematic class was present during Compile time and that's why the program successfully compiled but was not available during runtime for any reason. 

NoClassDefFoundError is easier to solve than ClassNotFoundException in my opinion because here we know that Class was present at build time, but it totally depends upon the environment if you are working in the J2EE environment then you can get NoClassDefFoundError even if the class is present because it may not be visible to the corresponding class loader. 

You can further see my post NoClassDefFoundError vs ClassNotFoundException in Java for more details.

How to resolve java.lang.NoClassDefFoundError in Java?

The obvious reason for NoClassDefFoundError is that a particular class is not available in Classpath, so we need to add that into Classpath or we need to check why it’s not available in Classpath if we are expecting it to be. There could be multiple reasons like:

1) The class is not available in Java Classpath.

2) You might be running your program using the jar command and class was not defined in the manifest file's ClassPath attribute.

3) Any start-up script is an overriding Classpath environment variable.

4) Because NoClassDefFoundError is a subclass of java.lang.LinkageError it can also come if one of it dependency like native library may not available.

4) Check for java.lang.ExceptionInInitializerError in your log file. NoClassDefFoundError due to the failure of static initialization is quite common.

5) If you are working in J2EE environment than the visibility of Class among multiple Classloader can also cause java.lang.NoClassDefFoundError, see examples and scenario section for detailed discussion.

We will now see a couple of examples and scenarios when java.lang.NoClassDefFoundError has come before and how it's been resolved. This can help you to troubleshoot the root cause of NoClassDefFoundError in Java application.

NoClassDefFoundError in Java - Example and Scenarios

1. A simple example of NoClassDefFoundError is class belongs to a missing JAR file or JAR was not added into classpath or sometimes jar's name has been changed by someone like in my case one of my colleagues has changed tibco.jar into tibco_v3.jar and the program is failing with java.lang.NoClassDefFoundError and I were wondering what's wrong.

2. The class is not in Classpath, there is no sure-shot way of knowing it but many times you can just have a look to print System.getproperty("java.classpath") and it will print the classpath from there you can at least get an idea of your actual runtime classpath.

3. Just try to run with explicitly -classpath option with the classpath you think will work and if it's working then it's a sure shot sign that someone is overriding java classpath.

NoClassDefFoundError in Java due to Exception in Static Initializer block

This is another common reason for java.lang.NoClassDefFoundError, when your class performs some static initialization in a static block like many Singleton classes initialized itself on the static block to take advantage of thread-safety provided by JVM during the class initialization process, and if static block throws an Exception, the class which is referring to this class will get NoclassDefFoundError in Java. 

If you look at your log file you should watch for any java.lang.ExceptionInInitializerError because that could trigger java.lang.NoClassDefFoundError: Could not initialize class on other places. 

Like in the below code example, During class loading and initialization User class are throwing Exception from the static initializer block, which triggers ExceptionInInitializerError during the first time loading of User class in response to new User() call.

Later rest of new User() are failing as java.lang.NoClassDefFoundError. the situation gets worst if original ExceptionInInitializerError, which is root cause here is silently eaten by any code.

Code Example of NoClassDefFoundError due to Static block Exception:

/**
 * Java program to demonstrate how failure of static initialization subsequently cause
 * java.lang.NoClassDefFoundError in Java.
 * @author Javin Paul
 */
public class NoClassDefFoundErrorDueToStaticInitFailure {

   public static void main(String args[]){
       
        List<User> users = new ArrayList<User>(2);
       
       for(int i=0; i<2; i++){
           try{
            users.add(new User(String.valueOf(i))); //will throw NoClassDefFoundError
           }catch(Throwable t){
                t.printStackTrace();
           }
       }        
   }
}

class User{
   private static String USER_ID = getUserId();
   
   public User(String id){
       this.USER_ID = id;
   }
   private static String getUserId() {
       throw new RuntimeException("UserId Not found");
   }    
}

Output
java.lang.ExceptionInInitializerError
    at testing.NoClassDefFoundErrorDueToStaticInitFailure.main(NoClassDefFoundErrorDueToStaticInitFailure.java:23)
Caused by: java.lang.RuntimeException: UserId Not found
    at testing.User.getUserId(NoClassDefFoundErrorDueToStaticInitFailure.java:41)
    at testing.User.<clinit>(NoClassDefFoundErrorDueToStaticInitFailure.java:35)
    ... 1 more
java.lang.NoClassDefFoundError: Could not initialize class testing.User
    at testing.NoClassDefFoundErrorDueToStaticInitFailure.main(NoClassDefFoundErrorDueToStaticInitFailure.java:23)

5) Since NoClassDefFoundError is an also a LinkageError that arises due to dependency on some other class, you can also get java.lang.NoClassDefFoundError if your program is dependent on the native library and the corresponding DLL is not there. Remember this can also trigger java.lang.UnsatisfiedLinkError: no dll in java.library.path Exception Java. In order to solve this keep your dll along with JAR.

6) If you are using the ANT build file create JAR and manifest file then its worth noting to debug till that level to ensure that ANT build script is getting the correct value of classpath and appending it to manifest.mf file.

7) Permission issue on the JAR file can also cause NoClassDefFoundError in Java. If you are running your Java program in a multi-user operating system like Linux then you should be using the application user id for all your application resources like JAR files, libraries, and configuration. 

If you are using a shared library which is shared among multiple application which runs under different users then you may run into permission issue, like JAR file is owned by some other user and not accessible to your application.

One of our readers “it’s me said”, faced java.lang.NoClassDefFoundError due to this reason. See his comment also.

8) Typo on XML Configuration can also cause NoClassDefFoundError in Java. As most of Java frameworks like Spring, Struts they all use XML configuration for specifying beans. By any chance, if you put the bean name wrong, it may surface as java.lang.NoClassDefFoundError while loading other class which has a dependency on the wrongly named bean. 

This is quite common in the Spring MVC framework and Apache Struts where you get tons of Exception in thread "main" java.lang.NoClassDefFoundError, while deploying your WAR or EAR file.

9) Another example of java.lang.NoClassDefFoundError, as mentioned by our reader Nick, is that when your compiled class which is defined in a package, doesn’t present in the same package while loading like in the case of JApplet it will throw NoClassDefFoundError in Java. Also, see Nick’s comment on this error.

10) java.lang.NoClassDefFoundError can be caused due to multiple classloaders in J2EE environments. Since J2EE doesn’t mention standard classloader structure and it depends on different vendors like Tomcat, WebLogic, WebSphere on how they load different components of J2EE like WAR file or EJB-JAR file. 

In order to troubleshoot NoClassDefFoundError in the J2EE application knowledge of How ClassLoader works in Java is mandatory. Just to recap ClasLoader works on three principles delegation, visibility, and uniqueness. 

Delegation means every request to load a class is delegated to the parent classloader, visibility means an ability to found classes loaded by the classloader, all child classloaders can see classes loaded by parent classloader, but parent classloader can not see the class loaded by child classloaders. 

Uniqueness enforces that class loaded by the parent will never be reloaded by child classloaders. Now suppose if a class says User is present in both WAR file and EJB-JAR file and loaded by WAR classloader which is child classloader which loads the class from EJB-JAR. When a code in EJB-JAR refers to this User class, Classloader which loaded all EJB class doesn’t found that because it was loaded by WAR classloader which is a child of it. 

This will result in java.lang.NoClassDefFoundError for User class. Also, If the class is present in both JAR file and you will call equals method to compare those two objects, it will result in ClassCastException as the object loaded by two different classloaders can not be equal.

11) Some of the readers of this blog also suggested that they get Exceptions in thread "main" java.lang.NoClassDefFoundError: com/sun/tools/javac/Main , this error means either your Classpath, PATH  or JAVA_HOME is not setup properly or JDK installation is not correct. which can be resolved by reinstalling JDK? 

If you are getting this error try to reinstall JDK. One of our readers got this issue after installing jdk1.6.0_33 and then reinstalling JDK1.6.0_25, he also has his JRE and JDK in a different folder. See his comment also by searching JDK1.6.0_33.

12) Java program can also throw java.lang.NoClassDefFoundError during linking which occurs during class loading in Java. One of the examples of this scenario is just deleted the User class from our static initializer failure example after compilation and they try to run the program. 

This time, you will get java.lang.NoClassDefFoundError directly without  java.lang.ExceptionInInitializerError and message for NoClassDefFoundError are also just printing the name of the class as testing/User i.e. User class from the testing package. Watch out for this carefully as here root cause is absent of User.class file.

java.lang.NoClassDefFoundError: testing/User
    at testing.NoClassDefFoundErrorDueToStaticInitFailure.main(NoClassDefFoundErrorDueToStaticInitFailure.java:23)

Let me know how exactly you are facing NoClassDefFoundError in Java and I will guide you on how to troubleshoot it if you are facing something new way than I listed above we will probably document it for the benefit of others and again don’t be afraid with Exception in thread "main" java.lang.NoClassDefFoundError.  

Other Exception and Error handling Tutorials from Javareivisted

• How to solve UnSupportedClassVersionError in Java
• Java.net.BindException: Address already in use: JVM_Bind:8080 Solution
• JDBC - java.lang.ClassNotFoundException: com.mysql.jdbc.Driver Solution
• How to Fix java.lang.classnotfoundexception oracle.jdbc.driver.oracledriver
• How to solve java.lang.ClassNotFoundException: org.Springframework.Web.Context.ContextLoaderListener 
• How to fix java.lang.ClassNotFoundException: org.apache.commons.logging.LogFactory
• How to solve java.lang.ClassNotFoundException: com.mysql.jdbc.Driver