How to Fix the ClassNotFound Exception in Java

When you run a Java program, the Java Virtual Machine (JVM) needs to load various classes to execute the program. The java.lang.ClassNotFoundException occurs when the JVM tries to load a particular class but doesn’t find it in the classpath.

One of the most common reasons for the ClassNotFoundException is missing third-party libraries. Double-checking that all necessary dependencies are included in the classpath and that the classpath is correctly configured can prevent this exception.

What Causes ClassNotFoundException

The classpath is a parameter that tells the JVM and the Java compiler where to look for user-defined classes and packages when running a program.

When you use any of the following methods to load a class but the JVM can’t find it in the classpath, java.lang.ClassNotFoundException is thrown.

• Class.forName()
• ClassLoader.findSystemClass()
• ClassLoader.loadClass()

If you get the ClassNotFoundException but are sure the class is there, what probably happened is one of these:

• The classpath might be incorrectly set up. The JAR file or directory containing the required classes is incorrect or the classpath is overridden by a start-up script or build configuration.
• Typos in the class name specified in methods like Class.forName()
• If the required class depends on other classes that are not present in the classpath, it can lead to the ClassNotFoundException. This is common in complex applications with many dependencies.
• Sometimes, using different versions of a library can cause this exception if the class you are trying to load is not present in the version of the library included in the classpath.
• In other cases, packaging issues can lead to this exception. For instance, if the classes are not properly packaged in the JAR file or if there are issues with the way the JAR file is built.

ClassNotFoundException Example

A very common example of the ClassNotFoundException is when a JDBC driver is attempted to be loaded using Class.forName() and the driver's JAR file is not present in the classpath:

public class ClassNotFoundExceptionExample {
    private static final String DRIVER_CLASS = "com.mysql.jdbc.Driver";

        public static void main(String[]  args) throws Exception {
                System.out.println("Loading MySQL JDBC driver");
                Class.forName(DRIVER_CLASS);
        }
            }

Since the MySQL JDBC driver JAR file is not present in the classpath, running the above code leads to a java.lang.ClassNotFoundException:

Loading MySQL JDBC driver
Exception in thread "main" java.lang.ClassNotFoundException: com.mysql.jdbc.Driver
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:602)
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:178)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:522)
    at java.base/java.lang.Class.forName0(Native Method)
    at java.base/java.lang.Class.forName(Class.java:340)
    at ClassNotFoundExceptionExample.main(ClassNotFoundExceptionExample.java:6)

To fix it, the mysql-connector JAR should be included in the application classpath.

ClassNotFoundException SolutionThe following steps should be followed to resolve a ClassNotFoundException in Java:

1. Find out which JAR file contains the problematic Java class. For example, in the case of com.mysql.jdbc.driver, the JAR file that contains it is mysql-connector-java.jar.
2. Check whether this JAR is present in the application classpath. If not, the JAR should be added to the classpath in Java and the application should be recompiled.
3. If that JAR is already present in the classpath, make sure the classpath is not overridden (e.g. by a start-up script). After finding out the exact Java classpath used by the application, the JAR file should be added to it.

To fix the Java exception, the mysql-connector JAR should be included in the application classpath.

What is the difference between ClassNotFoundException and NoClassDefFoundError?

ClassNotFoundException occurs when a class is missing at runtime, while NoClassDefFoundError happens when a class available during compile-time is missing at runtime.

ClassNotFoundException can be handled programmatically with try-catch blocks, but NoClassDefFoundError typically indicates a configuration or deployment issue that needs to be resolved outside the application's code. NoClassDefFoundError is a more serious problem and is harder to diagnose and fix compared to ClassNotFoundException.

Track, Analyze and Manage Java Errors With Rollbar

Managing errors and exceptions in your code is challenging. It can make deploying production code an unnerving experience. Being able to track, analyze, and manage errors in real-time can help you to proceed with more confidence. Rollbar automates Java error monitoring and triaging, making fixing errors easier than ever. Try it today.