java.lang.ClassNotFoundException: How to resolve

This article is intended for Java beginners facing java.lang.ClassNotFoundException challenges. It will provide you with an overview of this common Java exception, a sample Java program to support your learning process and resolution strategies.

If you are interested on more advanced class loader related problems, I recommended that you review my article series on java.lang.NoClassDefFoundError since these Java exceptions are closely related.

java.lang.ClassNotFoundException: Overview

As per the Oracle documentation, ClassNotFoundException is thrown following the failure of a class loading call, using its string name, as per below:

• The Class.forName method
• The ClassLoader.findSystemClass method
• The ClassLoader.loadClass method

In other words, it means that one particular Java class was not found or could not be loaded at “runtime” from your application current context class loader.

This problem can be particularly confusing for Java beginners. This is why I always recommend to Java developers to learn and refine their knowledge on Java class loaders. Unless you are involved in dynamic class loading and using the Java Reflection API, chances are that the ClassNotFoundException error you are getting is not from your application code but from a referencing API. Another common problem pattern is a wrong packaging of your application code. We will get back to the resolution strategies at the end of the article.

java.lang.ClassNotFoundException: Sample Java program

* A ClassNotFoundException YouTube video is now available.

Now find below a very simple Java program which simulates the 2 most common ClassNotFoundException scenarios via Class.forName() & ClassLoader.loadClass(). Please simply copy/paste and run the program with the IDE of your choice (Eclipse IDE was used for this example).

The Java program allows you to choose between problem scenario #1 or problem scenario #2 as per below. Simply change to 1 or 2 depending of the scenario you want to study.

# Class.forName()

private static final int PROBLEM_SCENARIO = 1;

# ClassLoader.loadClass()

private static final int PROBLEM_SCENARIO = 2;

# ClassNotFoundExceptionSimulator

package org.ph.javaee.training5;

/**

 * ClassNotFoundExceptionSimulator

 * @author Pierre-Hugues Charbonneau

 *

 */

public class ClassNotFoundExceptionSimulator {

      

       private static final String CLASS_TO_LOAD = "org.ph.javaee.training5.ClassA";

       private static final int PROBLEM_SCENARIO = 1;

      

       /**

        * @param args

        */

       public static void main(String[] args) {

            

             System.out.println("java.lang.ClassNotFoundException Simulator - Training 5");

             System.out.println("Author: Pierre-Hugues Charbonneau");

             System.out.println("http://javaeesupportpatterns.blogspot.com");

            

             switch(PROBLEM_SCENARIO) {

                   

                    // Scenario #1 - Class.forName()

                    case 1:

                          

                           System.out.println("\n** Problem scenario #1: Class.forName() **\n");

                           try {

                                 Class<?> newClass = Class.forName(CLASS_TO_LOAD);

                                

                                 System.out.println("Class "+newClass+" found successfully!");

                          

                           } catch (ClassNotFoundException ex) {

                                

                                 ex.printStackTrace();

                                

                                 System.out.println("Class "+CLASS_TO_LOAD+" not found!");

                          

                           } catch (Throwable any) {                           

                                 System.out.println("Unexpected error! "+any);

                           }

                          

                           break;

                          

                    // Scenario #2 - ClassLoader.loadClass()

                    case 2:

                          

                           System.out.println("\n** Problem scenario #2: ClassLoader.loadClass() **\n");                     

                           try {

                                 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();            

                                 Class<?> callerClass = classLoader.loadClass(CLASS_TO_LOAD);

                                

                                 Object newClassAInstance = callerClass.newInstance();

                                

                                 System.out.println("SUCCESS!: "+newClassAInstance);

                           } catch (ClassNotFoundException ex) {

                                

                                 ex.printStackTrace();

                                

                                 System.out.println("Class "+CLASS_TO_LOAD+" not found!");

                          

                           } catch (Throwable any) {                           

                                 System.out.println("Unexpected error! "+any);

                           }

                          

                           break;

             }

            

             System.out.println("\nSimulator done!");

       }

}

# ClassA

package org.ph.javaee.training5;

/**

 * ClassA

 * @author Pierre-Hugues Charbonneau

 *

 */

public class ClassA {

      

private final static Class<ClassA> CLAZZ = ClassA.class;

      

       static {

             System.out.println("Class loading of "+CLAZZ+" from ClassLoader '"+CLAZZ.getClassLoader()+"' in progress...");

       }

      

       public ClassA() {

             System.out.println("Creating a new instance of "+ClassA.class.getName()+"...");

            

             doSomething();

       }

      

       private void doSomething() {           

             // Nothing to do...

       }

}

If you run the program as is, you will see the output as per below for each scenario:

#Scenario 1 output (baseline)

java.lang.ClassNotFoundException Simulator - Training 5

Author: Pierre-Hugues Charbonneau

http://javaeesupportpatterns.blogspot.com

** Problem scenario #1: Class.forName() **

Class loading of class org.ph.javaee.training5.ClassA from ClassLoader 'sun.misc.Launcher$AppClassLoader@bfbdb0' in progress...

Class class org.ph.javaee.training5.ClassA found successfully!

Simulator done!

#Scenario 2 output (baseline)

java.lang.ClassNotFoundException Simulator - Training 5

Author: Pierre-Hugues Charbonneau

http://javaeesupportpatterns.blogspot.com

** Problem scenario #2: ClassLoader.loadClass() **

Class loading of class org.ph.javaee.training5.ClassA from ClassLoader 'sun.misc.Launcher$AppClassLoader@2a340e' in progress...

Creating a new instance of org.ph.javaee.training5.ClassA...

SUCCESS!: org.ph.javaee.training5.ClassA@6eb38a

Simulator done!

For the “baseline” run, the Java program is able to load ClassA successfully.

Now let’s voluntary change the full name of ClassA and re-run the program for each scenario. The following output can be observed:

#ClassA changed to ClassB

private static final String CLASS_TO_LOAD = "org.ph.javaee.training5.ClassB";

#Scenario 1 output (problem replication)

java.lang.ClassNotFoundException Simulator - Training 5

Author: Pierre-Hugues Charbonneau

http://javaeesupportpatterns.blogspot.com

** Problem scenario #1: Class.forName() **

java.lang.ClassNotFoundException: org.ph.javaee.training5.ClassB

       at java.net.URLClassLoader$1.run(URLClassLoader.java:366)

       at java.net.URLClassLoader$1.run(URLClassLoader.java:355)

       at java.security.AccessController.doPrivileged(Native Method)

       at java.net.URLClassLoader.findClass(URLClassLoader.java:354)

       at java.lang.ClassLoader.loadClass(ClassLoader.java:423)

       at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)

       at java.lang.ClassLoader.loadClass(ClassLoader.java:356)

       at java.lang.Class.forName0(Native Method)

       at java.lang.Class.forName(Class.java:186)

       at org.ph.javaee.training5.ClassNotFoundExceptionSimulator.main(ClassNotFoundExceptionSimulator.java:29)

Class org.ph.javaee.training5.ClassB not found!

Simulator done!

#Scenario 2 output (problem replication)

java.lang.ClassNotFoundException Simulator - Training 5

Author: Pierre-Hugues Charbonneau

http://javaeesupportpatterns.blogspot.com

** Problem scenario #2: ClassLoader.loadClass() **

java.lang.ClassNotFoundException: org.ph.javaee.training5.ClassB

       at java.net.URLClassLoader$1.run(URLClassLoader.java:366)

       at java.net.URLClassLoader$1.run(URLClassLoader.java:355)

       at java.security.AccessController.doPrivileged(Native Method)

       at java.net.URLClassLoader.findClass(URLClassLoader.java:354)

       at java.lang.ClassLoader.loadClass(ClassLoader.java:423)

       at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)

       at java.lang.ClassLoader.loadClass(ClassLoader.java:356)

       at org.ph.javaee.training5.ClassNotFoundExceptionSimulator.main(ClassNotFoundExceptionSimulator.java:51)

Class org.ph.javaee.training5.ClassB not found!

Simulator done!

What happened? Well since we changed the full class name to org.ph.javaee.training5.ClassB, such class was not found at runtime (does not exist), causing both Class.forName() and ClassLoader.loadClass() calls to fail.

You can also replicate this problem by packaging each class of this program to its own JAR file and then omit the jar file containing ClassA.class from the main class path  Please try this and see the results for yourself…(hint: NoClassDefFoundError)

Now let’s jump to the resolution strategies.

java.lang.ClassNotFoundException: Resolution strategies

Now that you understand this problem, it is now time to resolve it. Resolution can be fairly simple or very complex depending of the root cause.

• Don’t jump on complex root causes too quickly, rule out the simplest causes first.
• First review the java.lang.ClassNotFoundException stack trace as per the above and determine which Java class was not loaded properly at runtime e.g. application code, third party API, Java EE container itself etc.
• Identify the caller e.g. Java class you see from the stack trace just before the Class.forName() or ClassLoader.loadClass() calls. This will help you understand if your application code is at fault vs. a third party API.
• Determine if your application code is not packaged properly e.g. missing JAR file(s) from your classpath
• If the missing Java class is not from your application code, then identify if it belongs to a third party API you are using as per of your Java application. Once you identify it, you will need to add the missing JAR file(s) to your runtime classpath or web application WAR/EAR file.
• If still struggling after multiple resolution attempts, this could means a more complex class loader hierarchy problem. In this case, please review my NoClassDefFoundError article series for more examples and resolution strategies

I hope this article has helped you to understand and revisit this common Java exception.

Please feel free to post any comment or question if you are still struggling with your java.lang.ClassNotFoundException problem.

Read More

java.lang.NoClassDefFoundError: Parent first Classloader

This is part 4 of our “Exception in thread main java.lang.NoClassDefFoundError” troubleshooting series. As you saw from my previous articles, missing Jar files and failure of static initializers are the most common sources of this problem. However, sometimes the root cause is due to a more complex Java class loader problem which is quite common when developing Java EE applications involving multiple parent and child class loaders. The following article will describe one common problem pattern when using the default class loader delegation model.

A simple Java program will again be provided in order to help you understand this problem pattern.

Default JVM Classloader delegation model

As we saw from the first article, the default class loader delegation model is from bottom-up e.g. parent first. This means that the JVM is going up to the class loader chain in order to find and load each of your application Java classes. If the class is not found from the parent class loaders, the JVM will then attempt to load it from the current Thread context class loader; typically a child class loader.

NoClassDefFoundError problems can occur, for example, when you wrongly package your application (or third part API’s) between the parent and child class loaders. Another example is code / JAR files injection by the container itself or third party API’s deployed at a higher level in the class loader chain.

In the above scenarios:

• The JVM loads one part of the affected code to a parent class loader (SYSTEM or parent class loaders)
• The JVM loads the other parts of the affected code to a child class loader (Java EE container or application defined class loader)

Now what happens when Java classes loaded from the parent attempt to load reference classes deployed only to the child classloader? NoClassDefFoundError!

Please remember that a parent class loader has no visibility or access to child class loaders. This means that any referencing code must be found either from the parent class loader chain (bottom-up) or at the current Thread context class loader level; otherwise java.lang.NoClassDefFoundError is thrown by the JVM.

This is exactly what the following Java program will demonstrate.

Sample Java program

The following simple Java program is split as per below:

• The main Java program NoClassDefFoundErrorSimulator is packaged in MainProgram.jar
• A logging utility class JavaEETrainingUtil is packaged in MainProgram.jar
• The Java class caller CallerClassA is packaged in caller.jar
• The referencing Java class ReferencingClassA is packaged in referencer.jar

These following tasks are performed:

• Create a child class loader (java.net.URLClassLoader)
• Assign the caller and referencing Java class jar files to the child class loader
• Change the current Thread context ClassLoader to the child ClassLoader
• Attempt to load and create a new instance of CallerClassA from the current Thread context class loader e.g. child
• Proper logging was added in order to help you understand the class loader tree and Thread context class loader state

It will demonstrate that a wrong packaging of the application code is leading to a NoClassDefFoundError as per the default class loader delegation model.

** JavaEETrainingUtil source code can be found from the article part #2

#### NoClassDefFoundErrorSimulator.java

package org.ph.javaee.training3;

import java.net.URL;

import java.net.URLClassLoader;

import org.ph.javaee.training.util.JavaEETrainingUtil;

/**

 * NoClassDefFoundErrorSimulator

 * @author Pierre-Hugues Charbonneau

 *

 */

public class NoClassDefFoundErrorSimulator {

       

        /**

         * @param args

         */

        public static void main(String[] args) {

              

               System.out.println("java.lang.NoClassDefFoundError Simulator - Training 3");

               System.out.println("Author: Pierre-Hugues Charbonneau");

               System.out.println("http://javaeesupportpatterns.blogspot.com");

              

               // Local variables

               String currentThreadName = Thread.currentThread().getName();

               String callerFullClassName = "org.ph.javaee.training3.CallerClassA";

              

               // Print current ClassLoader context & Thread

               System.out.println("\nCurrent Thread name: '"+currentThreadName+"'");

               System.out.println("Initial ClassLoader chain: "+JavaEETrainingUtil.getCurrentClassloaderDetail());

              

               try {

                       // Location of the application code for our child ClassLoader

                       URL[] webAppLibURL = new URL[] {new URL("file:caller.jar"),new URL("file:referencer.jar")};

                      

                       // Child ClassLoader instance creation              

                       URLClassLoader childClassLoader = new URLClassLoader(webAppLibURL);

                      

                       /*** Application code execution... ***/

                      

                       // 1. Change the current Thread ClassLoader to the child ClassLoader

                       Thread.currentThread().setContextClassLoader(childClassLoader);

                       System.out.println(">> Thread '"+currentThreadName+"' Context ClassLoader now changed to '"+childClassLoader+"'");

                       System.out.println("\nNew ClassLoader chain: "+JavaEETrainingUtil.getCurrentClassloaderDetail());

                      

                       // 2. Load the caller Class within the child ClassLoader...

                       System.out.println(">> Loading '"+callerFullClassName+"' to child ClassLoader '"+childClassLoader+"'...");

                       Class<?> callerClass = childClassLoader.loadClass(callerFullClassName);

                      

                       // 3. Create a new instance of CallerClassA

                       Object callerClassInstance = callerClass.newInstance();                    

                      

               } catch (Throwable any) {

                       System.out.println("Throwable: "+any);

                       any.printStackTrace();

               }

              

               System.out.println("\nSimulator completed!");

        }

}

#### CallerClassA.java

package org.ph.javaee.training3;

import org.ph.javaee.training3.ReferencingClassA;

/**

 * CallerClassA

 * @author Pierre-Hugues Charbonneau

 *

 */

public class CallerClassA {

       

        private final static Class<CallerClassA> CLAZZ = CallerClassA.class;

       

        static {

               System.out.println("Class loading of "+CLAZZ+" from ClassLoader '"+CLAZZ.getClassLoader()+"' in progress...");

        }

       

        public CallerClassA() {

               System.out.println("Creating a new instance of "+CallerClassA.class.getName()+"...");

              

               doSomething();

        }

       

        private void doSomething() {

              

               // Create a new instance of ReferencingClassA

               ReferencingClassA referencingClass = new ReferencingClassA();             

        }

}

#### ReferencingClassA.java

package org.ph.javaee.training3;

/**

 * ReferencingClassA

 * @author Pierre-Hugues Charbonneau

 *

 */

public class ReferencingClassA {

       

        private final static Class<ReferencingClassA> CLAZZ = ReferencingClassA.class;

       

        static {

               System.out.println("Class loading of "+CLAZZ+" from ClassLoader '"+CLAZZ.getClassLoader()+"' in progress...");

        }

       

        public ReferencingClassA() {

               System.out.println("Creating a new instance of "+ReferencingClassA.class.getName()+"...");

        }

       

        public void doSomething() {

               //nothing to do...

        }

}

Problem reproduction

In order to replicate the problem, we will simply “voluntary” split the packaging of the application code (caller & referencing class) between the parent and child class loader.

For now, let’s run the program with the right JAR files deployment and class loader chain:

• The main program and utility class are deployed at the parent class loader (SYSTEM classpath)
• CallerClassA and ReferencingClassA and both deployed at the child class loader level

## Baseline (normal execution)

<JDK_HOME>\bin>java -classpath MainProgram.jar org.ph.javaee.training3.NoClassDefFoundErrorSimulator

java.lang.NoClassDefFoundError Simulator - Training 3

Author: Pierre-Hugues Charbonneau

http://javaeesupportpatterns.blogspot.com

Current Thread name: 'main'

Initial ClassLoader chain:

-----------------------------------------------------------------

sun.misc.Launcher$ExtClassLoader@17c1e333

--- delegation ---

sun.misc.Launcher$AppClassLoader@214c4ac9 **Current Thread 'main' Context ClassLoader**

-----------------------------------------------------------------

>> Thread 'main' Context ClassLoader now changed to 'java.net.URLClassLoader@6a4d37e5'

New ClassLoader chain:

-----------------------------------------------------------------

sun.misc.Launcher$ExtClassLoader@17c1e333

--- delegation ---

sun.misc.Launcher$AppClassLoader@214c4ac9

--- delegation ---

java.net.URLClassLoader@6a4d37e5 **Current Thread 'main' Context ClassLoader**

-----------------------------------------------------------------

>> Loading 'org.ph.javaee.training3.CallerClassA' to child ClassLoader 'java.net.URLClassLoader@6a4d37e5'...

Class loading of class org.ph.javaee.training3.CallerClassA from ClassLoader 'java.net.URLClassLoader@6a4d37e5' in progress...

Creating a new instance of org.ph.javaee.training3.CallerClassA...

Class loading of class org.ph.javaee.training3.ReferencingClassA from ClassLoader 'java.net.URLClassLoader@6a4d37e5' in progress...

Creating a new instance of org.ph.javaee.training3.ReferencingClassA...

Simulator completed!

For the initial run (baseline), the main program was able to create successfully a new instance of CallerClassA from the child class loader (java.net.URLClassLoader) along with its referencing class with no problem.

Now let’s run the program with the wrong application packaging and class loader chain:

• The main program and utility class are deployed at the parent class loader (SYSTEM classpath)
• CallerClassA and ReferencingClassA and both deployed at the child class loader level
• CallerClassA (caller.jar) is also deployed at the parent class loader level

## Problem reproduction run (static variable initializer failure)

<JDK_HOME>\bin>java -classpath MainProgram.jar;caller.jar org.ph.javaee.training3.NoClassDefFoundErrorSimulator

java.lang.NoClassDefFoundError Simulator - Training 3

Author: Pierre-Hugues Charbonneau

http://javaeesupportpatterns.blogspot.com

Current Thread name: 'main'

Initial ClassLoader chain:

-----------------------------------------------------------------

sun.misc.Launcher$ExtClassLoader@17c1e333

--- delegation ---

sun.misc.Launcher$AppClassLoader@214c4ac9 **Current Thread 'main' Context ClassLoader**

-----------------------------------------------------------------

>> Thread 'main' Context ClassLoader now changed to 'java.net.URLClassLoader@6a4d37e5'

New ClassLoader chain:

-----------------------------------------------------------------

sun.misc.Launcher$ExtClassLoader@17c1e333

--- delegation ---

sun.misc.Launcher$AppClassLoader@214c4ac9

--- delegation ---

java.net.URLClassLoader@6a4d37e5 **Current Thread 'main' Context ClassLoader**

-----------------------------------------------------------------

>> Loading 'org.ph.javaee.training3.CallerClassA' to child ClassLoader 'java.net.URLClassLoader@6a4d37e5'...

Class loading of class org.ph.javaee.training3.CallerClassA from ClassLoader 'sun.misc.Launcher$AppClassLoader@214c4ac9' in progress...// Caller is loaded from the parent class loader, why???

Creating a new instance of org.ph.javaee.training3.CallerClassA...

Throwable: java.lang.NoClassDefFoundError: org/ph/javaee/training3/ReferencingClassA

java.lang.NoClassDefFoundError: org/ph/javaee/training3/ReferencingClassA

        at org.ph.javaee.training3.CallerClassA.doSomething(CallerClassA.java:27)

        at org.ph.javaee.training3.CallerClassA.<init>(CallerClassA.java:21)

        at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)

        at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source)

        at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source)

        at java.lang.reflect.Constructor.newInstance(Unknown Source)

        at java.lang.Class.newInstance0(Unknown Source)

        at java.lang.Class.newInstance(Unknown Source)

        at org.ph.javaee.training3.NoClassDefFoundErrorSimulator.main(NoClassDefFoundErrorSimulator.java:51)

Caused by: java.lang.ClassNotFoundException: org.ph.javaee.training3.ReferencingClassA

        at java.net.URLClassLoader$1.run(Unknown Source)

        at java.net.URLClassLoader$1.run(Unknown Source)

        at java.security.AccessController.doPrivileged(Native Method)

        at java.net.URLClassLoader.findClass(Unknown Source)

        at java.lang.ClassLoader.loadClass(Unknown Source)

        at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)

        at java.lang.ClassLoader.loadClass(Unknown Source)

        ... 9 more

Simulator completed!

What happened?

• The main program and utility classes were loaded as expected from the parent class loader (sun.misc.Launcher$AppClassLoader)
• The Thread context class loader was changed to child class loader as expected which includes both caller and referencing jar files
• However, we can see that CallerClassA was actually loaded by the parent class loader (sun.misc.Launcher$AppClassLoader) instead of the child class loader
• Since ReferencingClassA was not deployed to the parent class loader, the class cannot be found from the current class loader chain since the parent  class loader has no visibility on the child class loader, NoClassDefFoundError is thrown

The key point to understand at this point is why CallerClassA was loaded by the parent class loader. The answer is with the default class loader delegation model. Both child and parent class loaders contain the caller JAR files. However, the default delegation model is always parent first which is why it was loaded at that level. The problem is that the caller contains a class reference to ReferencingClassA which is only deployed to the child class loader; java.lang.NoClassDefFoundError condition is met.

As you can see, a packaging problem of your code or third part API can easily lead to this problem due to the default class loader delegation behaviour. It is very important that you review your class loader chain and determine if you are at risk of duplicate code or libraries across your parent and child class loaders.

Recommendations and resolution strategies

Now find below my recommendations and resolution strategies for this problem pattern:

• Review the java.lang.NoClassDefFoundError error and identify the Java class that the JVM is complaining about
• Review the packaging of the affected application(s), including your Java EE container and third part API’s used. The goal is to identify duplicate or wrong deployments of the affected Java class at runtime (SYSTEM class path, EAR file, Java EE container itself etc.).
• Once identified, you will need to remove and / or move the affected library/libraries from the affected class loader (complexity of resolution will depend of the root cause).
• Enable JVM class verbose e.g. –verbose:class. This JVM debug flag is very useful to monitor the loading of the Java classes and libraries from the Java EE container your applications. It can really help you pinpoint duplicate Java class loading across various applications and class loaders at runtime

Please feel free to post any question or comment. The next and last article of this series will focus on NoClassDefFoundError when using the “child first” delegation model.

Read More