ClassNotFoundException in Java: Causes and Fixes

Where It Appears

ClassNotFoundException means Java was asked to load a class by name, but that class was not found on the runtime classpath. This commonly appears with JDBC drivers, reflection, plugin loading, servlet containers, and older framework configuration.

It is a checked exception, so code that calls Class.forName or similar loading APIs must handle or declare it. The real fix is usually not a try-catch block; it is correcting dependencies, class names, package names, or deployment packaging.

To debug it, compare compile-time dependencies with runtime dependencies. A class can exist in your IDE but still be missing from the JAR, WAR, server lib folder, or production runtime.

For project work, write dependency notes beside this error: library name, artifact name, version, and where the class should be packaged. That habit turns a vague classpath failure into a checklist you can verify step by step.

If the class belongs to your own project, confirm that the package declaration matches the folder path and that the compiled class is included in the final build output.

ClassNotFoundException often appears when a program loads a class dynamically using a string, such as Class.forName("com.mysql.cj.jdbc.Driver"). Since the compiler cannot verify the string, the problem is found only at runtime.

It can also happen in web applications when the server does not receive the dependency that your local project has. Maven scope, Gradle configuration, and manual JAR copying are common places to check.

Wrong fully qualified class name.
Missing dependency in runtime classpath.
Dependency marked with the wrong scope.
Class exists in a different library version.

Fixing Classpath and Dependency Problems

Start by copying the exact class name from the exception. Search for the class in your project and dependencies. If it belongs to a library, confirm that the library is installed and packaged with the application.

For Maven, check pom.xml and run dependency tree commands. For Gradle, inspect dependencies and runtimeClasspath. For servlet or application servers, confirm the required JAR is inside WEB-INF/lib or provided by the server correctly.

Use the full package name, not only the simple class name.
Match dependency versions with framework documentation.
Avoid duplicate old and new driver JARs together.
Rebuild the artifact after dependency changes.

ClassNotFoundException vs NoClassDefFoundError

ClassNotFoundException is usually thrown when code explicitly asks Java to load a class by name. NoClassDefFoundError usually means the class was available during compilation but missing or unusable at runtime.

Both can point to classpath problems, but the stack trace and error type help you locate whether dynamic loading or binary/runtime packaging is the main issue.

ClassNotFoundException is checked.
NoClassDefFoundError is an Error.
Both may be caused by missing JARs.
Always inspect the runtime environment, not just the source code.

Prove What Reached the Runtime Classpath

Do not stop after confirming that a dependency appears in the IDE. Inspect the artifact that is actually launched or deployed. An executable JAR, WAR file, container image, test runner, and application server can each assemble a different runtime classpath.

Use jar tf to inspect packaged files, then compare the result with the runtime dependency report. For your own class, its protection domain can reveal the JAR or classes directory that supplied it. This evidence separates a missing artifact from a misspelled class name or a class-loader boundary problem.

Inspect executable JAR libraries or the WEB-INF/lib directory inside a WAR.
For Maven, inspect dependency:tree with runtime scope; for Gradle, inspect the runtimeClasspath configuration.
Check container images, startup scripts, and server library folders for deployment-only differences.
After correcting packaging, rebuild from clean output and verify the deployed artifact again.

Dynamic Class Loading Example

public class DriverCheck {
    public static void main(String[] args) {
        try {
            Class.forName("com.mysql.cj.jdbc.Driver");
            System.out.println("Driver found");
        } catch (ClassNotFoundException ex) {
            System.out.println("Add the MySQL connector dependency to the runtime classpath.");
        }
    }
}

Maven Dependency Example

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.4.0</version>
</dependency>

Before you move on