How do I resolve ClassNotFoundException?

As the nomenclature implies, a ClassNotFoundException in Java arises when the Java Virtual Machine (JVM) endeavors to load a specific class but fails to locate the requested class within the specified classpath. This predicament often arises due to a broken classpath, a prevalent issue in the Java area. For neophyte Java programmers, this can be a perplexing challenge. It is essential to note that ClassNotFoundException is a checked exception, mandating either its capture within a catch block or propagation to the caller through the throws clause, in order to maintain proper exception handling and ensure the program's stability.

Java ClassNotFoundException sample

One of the most frequent scenarios leading to a ClassNotFoundException is encountered when attempting to load JDBC drivers using Class.forName, yet inadvertently neglecting to include the corresponding JAR file in the classpath. This omission results in the Java Virtual Machine (JVM) being unable to find the specified driver class, leading to the ClassNotFoundException being thrown. To rectify this situation, it is imperative to ensure that the necessary JAR file containing the JDBC driver is appropriately added to the classpath, thereby facilitating the seamless loading of the desired class during runtime.

Java ClassNotFoundException

When ClassNotFoundException occurs in Java

Java ClassNotFoundException thrown when an application tries to load in a class through its string name using:

  1. The forName method in class Class.
  2. The findSystemClass method in class ClassLoader .
  3. The loadClass method in class ClassLoader.

Java ClassNotFoundException example

In the following example, there is no such class exist and try to attempt to load the class "NoClassExist".

public class Example { public static void main(String args[]) { try { Class.forName("NoClassExist"); } catch (ClassNotFoundException ex) { ex.printStackTrace(); } } }
java.lang.ClassNotFoundException: NoClassExist

Java Class.forName()

After the successful compilation of your Java code, the resulting output comprises .class files, which contain the bytecode interpreted by Java during program execution. However, instances of ClassNotFoundException may arise when attempting to load classes dynamically at runtime using methods like Class.forName() or loadClass(), but the requested classes cannot be located within the specified classpath. Another situation leading to this exception involves the presence of multiple class loaders, where one ClassLoader attempts to access a class that has already been loaded by another ClassLoader. This scenario may also trigger a ClassNotFoundException in Java. To address such occurrences, careful management of the classpath and handling of class loading mechanisms is crucial for seamless program execution.

Exception Hierarchy

Java ClassNotFoundExceptionException Hierarchy

How to fix the ClassNotFoundException

  1. Review properly the java.lang.ClassNotFoundException stack trace which Java class was not loaded properly at runtime.

  2. Verify the name of the requested class is correct and the specified .jar file exists in your classpath. If not, you must explicitly add it to your application’s classpath.

  3. If it's present in your classpath then there is high chance that your classpath is getting overridden or application is using classpath specified in jar file or start-up script and to fix that you need to find the exact classpath used by your application.

  4. In case the exception is caused by a third party class, you must identify the class that throws the exception and then, add the missing .jar files in your classpath.

Java Classpath and ClassNotFoundException

  1. Java classpath is a list of locations to load classes from. These locations can either be directories, or jar files. For directories, the Java Virtual Machine will follow an expected pattern for loading a class.
  1. For example, if you have the directory C:/java/classes in your classpath, and you attempt to load a class com.myproject.myprog, it will look under the classes directory for a directory called com, then under that a directory called myproject, and finally it will look for a file called myprog.class in that directory.
  1. In case of jar files, it will search the jar file for that class. A jar file is a zipped collection of directories like the above. If you unzip a jar file, you'll get a bunch of directories and class files following the pattern above.
  1. So the Java Virtual Machine traverses a classpath from start to finish looking for the definition of the class when it attempts to load the class definition. For example, in the classpath :
  1. The Java Virtual Machine will attempt to look in the directory classes first, then in abc.jar and finally in xyz.jar.


When a ClassNotFoundException is encountered, it indicates that the Java Virtual Machine (JVM) has diligently searched through the entirety of the specified classpath, yet the targeted class remains elusive. In such situations, the primary and sole recourse is to carefully scrutinize the classpath configuration. Ensuring that the classpath is accurately set up to include the required class and its dependencies is imperative to resolving this exception. Thoroughly verifying the classpath configuration will pave the way for the successful location and loading of the desired class during runtime execution.