Java ClassNotFoundException — What It Means & How to Fix It

What Does This Error Mean?

A ClassNotFoundException means Java tried to load a class by name at runtime but could not find it anywhere in the classpath. This is different from a compile error — the code compiled fine, but when it ran, the class was missing. This usually means a required JAR file is missing, a dependency was not included, or there is a typo in the class name.

Affected Models

Java 8
Java 11
Java 17
Java 21
All Java versions

Common Causes

A required JAR file or library is missing from the project's classpath or build dependencies
The fully qualified class name (like 'com.mysql.jdbc.Driver') was typed incorrectly in a string
A Maven or Gradle dependency was not added to the build file, so the JAR was never downloaded
The application was repackaged or deployed without including all required libraries
Using Class.forName() with a class name from user input or a config file that contains a wrong value

How to Fix It

Read the error message — it includes the exact class name Java was looking for. Check for typos in that name, especially if it came from a string in your code or a config file.

Class names in Java are case-sensitive. 'com.mysql.jdbc.Driver' is different from 'com.mysql.jdbc.driver'.
Check your build file (pom.xml for Maven, build.gradle for Gradle) and confirm the required library is listed as a dependency. If it is missing, add it and rebuild.

For example, if you are using a MySQL database, you need the MySQL JDBC driver JAR in your dependencies.
If you are deploying a web application or JAR, check that all dependency JARs are included in the deployment package. A common mistake is compiling with libraries available locally but not packaging them.

In Maven, use the 'maven-shade-plugin' or 'maven-assembly-plugin' to create a fat JAR that includes all dependencies.
If you are using Class.forName() to load a class dynamically, double-check the full class name string. Even a single character difference will cause this error.

You can test the class name by searching for it in your IDE — if the IDE cannot find it, the class name is wrong or the library is missing.
Clean and rebuild your project. Sometimes old compiled files conflict with new ones. In Maven: mvn clean install. In Gradle: gradle clean build.

If using an IDE like IntelliJ or Eclipse, use File > Invalidate Caches or Project > Clean to force a full rebuild.

When to Call a Professional

ClassNotFoundException is a checked exception — Java forces you to handle it. It almost always means a missing dependency or a typo in a class name string. Check your build tool (Maven or Gradle) dependencies first, then check the exact class name.

Frequently Asked Questions

What is the difference between ClassNotFoundException and NoClassDefFoundError?

ClassNotFoundException is thrown when you explicitly try to load a class by name using Class.forName() or similar, and it is not found. NoClassDefFoundError is thrown when a class was available at compile time but is missing when the program actually runs. Both mean a class is missing — but the cause and the timing are different.

Why does ClassNotFoundException happen even when the JAR file is in my project folder?

Having the JAR file in a folder is not enough — it must be on the classpath. The classpath is the list of places Java actually looks for classes. In Maven and Gradle projects, adding a dependency to the build file is what puts it on the classpath.

Can ClassNotFoundException happen with JDBC database drivers?

Yes — this is one of the most common places developers see this error. Older code uses Class.forName('com.mysql.jdbc.Driver') to register a database driver. If the JDBC driver JAR is not on the classpath, this line will throw ClassNotFoundException.