--- # === IDENTITY === id: software/debugging/java-classnotfoundexception/2026 canonical_question: "How do I fix Java ClassNotFoundException and NoClassDefFoundError?" aliases: - "java.lang.ClassNotFoundException fix" - "java.lang.NoClassDefFoundError fix" - "Java class not found classpath" - "ClassNotFoundException vs NoClassDefFoundError difference" - "Java missing class at runtime" - "Maven ClassNotFoundException dependency" - "Gradle NoClassDefFoundError runtime" - "Java JDBC driver ClassNotFoundException" - "Class.forName ClassNotFoundException" - "Java fat JAR NoClassDefFoundError" entity_type: software_reference domain: software > debugging > java_classnotfoundexception region: global jurisdiction: global temporal_scope: 2000-2026 # === VERIFICATION === last_verified: 2026-02-23 confidence: 0.94 version: 1.0 first_published: 2026-02-23 # === TEMPORAL VALIDITY === temporal_validity: status: stable last_breaking_change: "Java 9 module system (JPMS) introduced new class visibility rules (2017)" next_review: 2026-08-22 change_sensitivity: low # === CONSTRAINTS === constraints: - "ClassNotFoundException is a checked exception (extends Exception); NoClassDefFoundError is an unchecked error (extends Error) — they require different handling strategies" - "NoClassDefFoundError caused by a failed static initializer will never show the original exception on retry — only the first load attempt throws ExceptionInInitializerError with the root cause" - "Java 9+ module system (JPMS) adds module visibility rules on top of classpath — a class may exist on the module path but remain inaccessible without proper exports/opens declarations" - "In application servers (Tomcat, WildFly, WebSphere), classloader hierarchies override standard classpath behavior — a JAR in the wrong classloader scope causes ClassNotFoundException even if present on disk" - "Case sensitivity matters: the JVM requires exact case match for fully qualified class names on all platforms, even though Windows filesystems are case-insensitive" # === SKIP CONDITIONS === skip_this_unit_if: - condition: "The error is java.lang.ClassCastException (class exists but wrong type/classloader)" use_instead: "Check for duplicate JARs loaded by different classloaders — ClassCastException means two classloaders loaded the same class, creating incompatible types" - condition: "The error is java.lang.UnsupportedClassVersionError (class compiled with newer JDK)" use_instead: "Recompile with the target JDK version or upgrade the runtime JDK — this is a bytecode version mismatch, not a missing class" - condition: "The error is java.lang.IncompatibleClassChangeError (method signature changed)" use_instead: "Rebuild all dependent JARs against the same library version — this is a binary compatibility issue from mixing JAR versions" - condition: "The error is java.lang.OutOfMemoryError: Metaspace (too many classes loaded)" use_instead: "software/debugging/java-outofmemoryerror/2026 — this is a memory issue, not a missing class issue" # === AGENT HINTS === inputs_needed: - key: "error_type" question: "Which error are you seeing: ClassNotFoundException or NoClassDefFoundError?" type: choice options: ["ClassNotFoundException", "NoClassDefFoundError", "Both / Not sure"] - key: "build_tool" question: "What build tool is the project using?" type: choice options: ["Maven", "Gradle", "Manual classpath (java -cp)", "Application server (Tomcat/WildFly)", "IDE only"] - key: "context" question: "When does the error occur?" type: choice options: ["Application startup", "Runtime (after running for a while)", "During testing", "After deployment/packaging", "During dynamic class loading (Class.forName, reflection)"] # === DISTRIBUTION === canonical_source: "https://knowledgelib.io/software/debugging/java-classnotfoundexception/2026" suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-02-23)" # === RELATED UNITS === related_kos: depends_on: [] related_to: - id: "software/debugging/java-outofmemoryerror/2026" label: "Java OutOfMemoryError Diagnosis" - id: "software/debugging/spring-boot-npe/2026" label: "Spring Boot NullPointerException Debugging" often_confused_with: - id: "software/debugging/java-classcastexception/2026" label: "Java ClassCastException (class exists but loaded by different classloader)" - id: "software/debugging/java-unsupportedclassversionerror/2026" label: "Java UnsupportedClassVersionError (bytecode version mismatch, not missing class)" solves: [] alternative_to: [] # === SOURCES (7 authoritative sources) === sources: - id: src1 title: "ClassNotFoundException (Java SE 21 & JDK 21)" author: Oracle url: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ClassNotFoundException.html type: official_docs published: 2024-01-01 reliability: authoritative - id: src2 title: "NoClassDefFoundError (Java SE 21 & JDK 21)" author: Oracle url: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/NoClassDefFoundError.html type: official_docs published: 2024-01-01 reliability: authoritative - id: src3 title: "ClassNotFoundException vs NoClassDefFoundError" author: Baeldung url: https://www.baeldung.com/java-classnotfoundexception-and-noclassdeffounderror type: technical_blog published: 2024-08-01 reliability: high - id: src4 title: "How to Fix the ClassNotFound Exception in Java" author: Rollbar url: https://rollbar.com/blog/how-to-resolve-classnotfoundexception-in-java/ type: technical_blog published: 2024-06-01 reliability: high - id: src5 title: "How to Resolve the NoClassDefFoundError in Java" author: Rollbar url: https://rollbar.com/blog/java-no-class-def-found-error/ type: technical_blog published: 2024-06-01 reliability: high - id: src6 title: "ClassNotFoundException Vs NoClassDefFoundError in Java" author: GeeksforGeeks url: https://www.geeksforgeeks.org/java/classnotfoundexception-vs-noclassdeffounderror-java/ type: community_resource published: 2024-01-15 reliability: moderate_high - id: src7 title: "Java.lang.NoClassDefFoundError: Causes and Solutions" author: ioflood url: https://ioflood.com/blog/java-lang-noclassdeffounderror/ type: technical_blog published: 2024-03-01 reliability: moderate_high --- # How Do I Fix Java ClassNotFoundException and NoClassDefFoundError? ## TL;DR - **Bottom line**: `ClassNotFoundException` is a checked exception thrown during explicit dynamic class loading (`Class.forName()`, `ClassLoader.loadClass()`); `NoClassDefFoundError` is an unchecked error thrown by the JVM when a class present at compile time is missing at runtime. Both are ultimately classpath problems, but they require different diagnostic approaches. - **Key tool/command**: `mvn dependency:tree` (Maven) or `gradle dependencies` (Gradle) to find missing/conflicting dependencies, and `java -verbose:class` to trace which classes the JVM loads and from where. - **Watch out for**: `NoClassDefFoundError` caused by a failed static initializer -- the original `ExceptionInInitializerError` only appears on the first attempt; subsequent calls show `NoClassDefFoundError` with no root cause. - **Works with**: Java 8+ (all current LTS versions: 8, 11, 17, 21). Java 9+ module system (JPMS) adds additional class visibility constraints. ## Constraints - `ClassNotFoundException` is a checked exception (`extends ReflectiveOperationException extends Exception`) that must be caught or declared; `NoClassDefFoundError` is an error (`extends LinkageError extends Error`) that should not be caught for retry logic -- it indicates a broken runtime environment. [src1, src2] - When `NoClassDefFoundError` is caused by a failed static initializer, the original `ExceptionInInitializerError` is thrown only on the first class load attempt. All subsequent attempts throw `NoClassDefFoundError` with no cause chain -- check logs for the initial `ExceptionInInitializerError`. [src3, src5] - In Java 9+ module system (JPMS), a class can be present on the module path but inaccessible without `exports` or `opens` declarations in `module-info.java`. Adding `--add-opens` or `--add-exports` JVM flags is a workaround, not a fix. [src1] - Application servers (Tomcat, WildFly, WebSphere) use hierarchical classloaders. Placing a dependency in the wrong scope (e.g., `WEB-INF/lib` vs server `lib/`) causes `ClassNotFoundException` even when the JAR exists on disk. [src4, src5] - Never suppress `NoClassDefFoundError` in a catch block and continue execution -- the JVM's class resolution is cached, and the class will never load successfully in the same JVM session once it has failed. [src2, src3] ## Quick Reference | # | Cause | Likelihood | Signature | Fix | |---|---|---|---|---| | 1 | Missing dependency JAR | ~30% | `ClassNotFoundException: com.example.SomeClass` during `Class.forName()` or framework init | Add the missing dependency to `pom.xml`/`build.gradle` or `-cp` [src4] | | 2 | Dependency version mismatch | ~20% | `NoClassDefFoundError: com/example/SomeClass` -- class existed at compile time but different JAR version at runtime | Run `mvn dependency:tree` and resolve version conflicts [src4, src5] | | 3 | Fat JAR packaging issue | ~15% | `NoClassDefFoundError` after `mvn package` / `gradle build` -- dependencies not bundled | Use `maven-shade-plugin` or `spring-boot-maven-plugin`; Gradle: `shadowJar` [src5] | | 4 | Failed static initializer | ~10% | First: `ExceptionInInitializerError`; then repeated: `NoClassDefFoundError: Could not initialize class X` | Fix the exception in the static block/field initializer [src3, src5] | | 5 | Wrong classloader scope (app server) | ~8% | `ClassNotFoundException` in Tomcat/WildFly despite JAR on disk | Move JAR to correct classloader scope (`WEB-INF/lib` vs server `lib/`) [src4] | | 6 | Typo in fully qualified class name | ~5% | `ClassNotFoundException: com.example.MyClss` (misspelled) in `Class.forName()` | Fix the class name string; Java is case-sensitive [src4, src6] | | 7 | Missing transitive dependency | ~4% | `NoClassDefFoundError` for a class you never imported directly | Run `mvn dependency:tree -Dverbose` to find excluded/missing transitive deps [src4] | | 8 | JDBC driver not on classpath | ~3% | `ClassNotFoundException: com.mysql.cj.jdbc.Driver` or `org.postgresql.Driver` | Add JDBC driver dependency; modern drivers auto-register via SPI (no `Class.forName()` needed) [src4] | | 9 | Java module system (JPMS) visibility | ~2% | `ClassNotFoundException` or `IllegalAccessError` in Java 9+ modular apps | Add `requires`, `exports`, or `opens` in `module-info.java`; use `--add-opens` as workaround [src1] | | 10 | Classpath ordering conflict | ~2% | Intermittent `NoClassDefFoundError` -- class exists in multiple JARs | Use `mvn dependency:tree` to identify duplicates; exclude unwanted JARs [src4, src5] | | 11 | ProGuard/R8 removed class | ~1% | `ClassNotFoundException` after obfuscation/minification | Add `-keep` rules for dynamically loaded classes [src4] | ## Decision Tree > Full script: [decision-tree.txt](scripts/decision-tree.txt) (26 lines) ``` START -- ClassNotFoundException or NoClassDefFoundError? | +-- ClassNotFoundException? | +-- Using Class.forName() / ClassLoader.loadClass()? | | +-- YES --> Check class name for typos; verify JAR on classpath (Cause #6, #1) # ... (see full script) ``` ## Step-by-Step Guide ### 1. Read the full stack trace and identify the error type The error message tells you exactly which class is missing and whether it is a `ClassNotFoundException` (checked exception, dynamic loading) or `NoClassDefFoundError` (error, compile-time dependency missing at runtime). [src1, src2] ```bash # Search logs for the specific error grep -E "ClassNotFoundException|NoClassDefFoundError|ExceptionInInitializerError" application.log # Key patterns: # java.lang.ClassNotFoundException: com.example.MyClass # --> Dynamic loading failed (Class.forName, classloader) # java.lang.NoClassDefFoundError: com/example/MyClass # --> Class existed at compile time but missing/broken at runtime # java.lang.ExceptionInInitializerError # Caused by: # --> Static initializer failed; next load will be NoClassDefFoundError ``` **Verify**: You have identified the exact fully qualified class name (e.g., `com.example.MyClass`) and the error type. ### 2. Find which JAR contains the missing class Use your build tool or manual search to identify the JAR that should provide the class. [src4] ```bash # Maven: search for class in local repository find ~/.m2/repository -name "*.jar" -exec sh -c \ 'jar tf "$1" | grep -q "com/example/MyClass.class" && echo "$1"' _ {} \; # Gradle: search dependency cache find ~/.gradle/caches -name "*.jar" -exec sh -c \ 'jar tf "$1" | grep -q "com/example/MyClass.class" && echo "$1"' _ {} \; # Or use Maven Central search: # https://search.maven.org/ (search by class name) ``` **Verify**: You know the exact `groupId:artifactId:version` that contains the class. ### 3. Check your dependency tree for conflicts Dependency version conflicts are the #1 cause in Maven/Gradle projects. A transitive dependency may pull in a different version that lacks the needed class. [src4, src5] ```bash # Maven: full dependency tree with conflict markers mvn dependency:tree -Dverbose # Maven: check effective classpath mvn dependency:build-classpath # Gradle: full dependency tree ./gradlew dependencies --configuration runtimeClasspath # Gradle: dependency insight for a specific module ./gradlew dependencyInsight --dependency commons-lang3 --configuration runtimeClasspath ``` **Verify**: `mvn dependency:tree` shows the expected version of the required JAR without `(omitted for conflict)` markers. ### 4. Add or fix the dependency Based on what you found, add the missing dependency or resolve the version conflict. [src4, src5] ```xml com.example missing-library 2.1.0 com.example conflicting-library 3.0.0 ``` ```groovy // Gradle: build.gradle // Add missing dependency dependencies { implementation 'com.example:missing-library:2.1.0' } // Force a specific version to resolve conflicts configurations.all { resolutionStrategy { force 'com.example:conflicting-library:3.0.0' } } ``` **Verify**: `mvn dependency:tree | grep missing-library` or `./gradlew dependencies | grep missing-library` shows the correct version. ### 5. Verify packaging includes all dependencies For standalone deployments (fat JARs), ensure all dependencies are bundled. [src5] ```xml org.springframework.boot spring-boot-maven-plugin org.apache.maven.plugins maven-shade-plugin 3.5.1 package shade ``` ```groovy // Gradle: shadow plugin for fat JARs plugins { id 'com.github.johnrengelman.shadow' version '8.1.1' } shadowJar { archiveClassifier.set('') mergeServiceFiles() // critical for SPI (JDBC drivers, etc.) } ``` **Verify**: `jar tf target/myapp.jar | grep com/example/MyClass.class` confirms the class is in the packaged JAR. ### 6. Fix static initializer failures (NoClassDefFoundError: Could not initialize class) If `NoClassDefFoundError` says "Could not initialize class", the real error is in a static block or static field initializer. [src3, src5] ```java // BAD: static initializer that can fail at runtime public class Config { // This will throw ExceptionInInitializerError on first access // and NoClassDefFoundError on every subsequent access private static final String VALUE = System.getenv("REQUIRED_VAR").toUpperCase(); // NPE if env var missing! static { // Any uncaught exception here prevents the class from ever loading Connection conn = DriverManager.getConnection(DB_URL); // can throw SQLException } } // GOOD: defensive static initialization public class Config { private static final String VALUE; static { String env = System.getenv("REQUIRED_VAR"); VALUE = (env != null) ? env.toUpperCase() : "DEFAULT"; } // Or: defer initialization to instance/method level private Connection getConnection() { return DriverManager.getConnection(DB_URL); } } ``` **Verify**: Search logs for the first `ExceptionInInitializerError` to find the root cause; fix the underlying exception, then restart the JVM. ## Code Examples ### Java: safe dynamic class loading with proper error handling ```java // Input: Fully qualified class name as String // Output: Loaded Class object or clear diagnostic error public static Class loadClassSafely(String className) { try { // 1. Try Thread context classloader first (works in app servers) return Thread.currentThread() .getContextClassLoader() .loadClass(className); } catch (ClassNotFoundException e1) { try { // 2. Fallback to Class.forName (uses caller's classloader) return Class.forName(className); } catch (ClassNotFoundException e2) { throw new RuntimeException( "Class '" + className + "' not found. " + "Check: (1) JAR containing this class is on the classpath, " + "(2) class name is spelled correctly (case-sensitive), " + "(3) dependency version includes this class.", e2); } } } ``` ### Maven: diagnosing and fixing dependency conflicts ```xml com.example library-a 1.0.0 com.google.guava guava com.google.guava guava 33.0.0-jre ``` ### Gradle: diagnosing and fixing dependency conflicts ```groovy // Input: build.gradle with conflicting dependencies // Output: Clean resolution with forced version // Step 1: Find conflicts // Run: ./gradlew dependencyInsight --dependency guava --configuration runtimeClasspath // Step 2: Force a specific version globally configurations.all { resolutionStrategy { force 'com.google.guava:guava:33.0.0-jre' } } // Step 3: Or exclude from a specific dependency dependencies { implementation('com.example:library-a:1.0.0') { exclude group: 'com.google.guava', module: 'guava' } implementation 'com.google.guava:guava:33.0.0-jre' } ``` ## Anti-Patterns ### Wrong: Catching NoClassDefFoundError and retrying ```java // BAD -- NoClassDefFoundError is cached by the JVM; the class will NEVER load [src2, src3] for (int i = 0; i < 3; i++) { try { return new com.example.MyService(); } catch (NoClassDefFoundError e) { System.out.println("Retry " + (i + 1) + "..."); Thread.sleep(1000); // Pointless -- the JVM will throw the same error every time } } ``` ### Correct: Fix the classpath and restart the JVM ```java // GOOD -- fix the root cause, don't retry [src2, src3] // 1. Add the missing JAR to the classpath // 2. Restart the JVM (NoClassDefFoundError state is cached per JVM session) // 3. For static initializer failures, fix the exception in the static block // and restart -- the JVM caches the failed initialization permanently ``` ### Wrong: Using Class.forName() for JDBC drivers in modern Java ```java // BAD -- unnecessary since JDBC 4.0 (Java 6+); driver auto-registers via SPI [src4] Class.forName("com.mysql.cj.jdbc.Driver"); // Throws ClassNotFoundException if JAR missing Connection conn = DriverManager.getConnection(url, user, pass); ``` ### Correct: Rely on JDBC 4.0 SPI auto-discovery ```java // GOOD -- just ensure the driver JAR is on the classpath [src4] // JDBC 4.0+ drivers register via META-INF/services/java.sql.Driver Connection conn = DriverManager.getConnection( "jdbc:mysql://localhost:3306/mydb", "user", "pass"); // If this throws ClassNotFoundException, the driver JAR is missing from classpath ``` ### Wrong: Using provided scope for runtime dependencies (Maven) ```xml com.google.guava guava 33.0.0-jre provided ``` ### Correct: Use compile (default) scope for application dependencies ```xml com.google.guava guava 33.0.0-jre ``` ## Common Pitfalls - **ClassNotFoundException vs NoClassDefFoundError confusion**: `ClassNotFoundException` occurs during explicit dynamic loading (`Class.forName()`); `NoClassDefFoundError` occurs when the JVM itself tries to resolve a class reference that existed at compile time. They look similar but have different causes and different handling requirements. [src3, src6] - **Maven scope `provided` vs `compile`**: Dependencies with `provided` are excluded from the packaged artifact. If the runtime container does not actually provide the dependency, you get `ClassNotFoundException`. Only use `provided` for APIs the container truly supplies (e.g., `javax.servlet-api`). [src4] - **Lost root cause in static initializer failures**: The first load of a class with a failing static block throws `ExceptionInInitializerError` with the real exception. Every subsequent attempt throws `NoClassDefFoundError` with no cause. The fix is to find the first error in logs. [src3, src5] - **Gradle `implementation` vs `api` scope**: `implementation` dependencies are not exposed to downstream consumers. If module B depends on module A, and A declares library X as `implementation`, module B cannot see X's classes at compile time, leading to `NoClassDefFoundError`. Use `api` scope for classes exposed in your public API. [src5] - **Fat JAR service file merging**: When using `maven-shade-plugin` or `shadowJar`, SPI service files (`META-INF/services/*`) from multiple JARs can overwrite each other. This breaks JDBC driver auto-registration, logging backends, etc. Always enable `ServicesResourceTransformer` (shade) or `mergeServiceFiles()` (shadow). [src5, src7] - **IDE classpath differs from build tool classpath**: A project may compile fine in IntelliJ/Eclipse but fail at runtime because the IDE resolves dependencies differently than `mvn package` or `gradle build`. Always verify with the build tool's classpath. [src4] - **Tomcat parent-first vs child-first classloading**: Tomcat's default classloader loads application classes (`WEB-INF/classes`, `WEB-INF/lib`) before delegating to the parent. Placing a dependency in `$CATALINA_HOME/lib` instead of `WEB-INF/lib` can cause version conflicts or `ClassNotFoundException` depending on classloader delegation order. [src4] ## Diagnostic Commands > Full script: [diagnostic-commands.sh](scripts/diagnostic-commands.sh) (32 lines) ```bash # === Trace class loading at runtime === java -verbose:class -cp "lib/*:myapp.jar" com.example.Main 2>&1 | grep "MyMissingClass" # Shows: [Loaded com.example.MyMissingClass from file:/path/to/library.jar] # If no output, the class is never found/loaded # === Print the effective classpath === # ... (see full script) ``` ## Version History & Compatibility | Java Version | ClassLoader/Class Changes | Impact on ClassNotFoundException/NoClassDefFoundError | |---|---|---| | Java 1.0-7 | Single classpath, flat classloader | Standard classpath rules; `-cp` or `CLASSPATH` env var | | Java 8 | Last version without module system | Most guides and Stack Overflow answers target this version | | Java 9 | Module system (JPMS) introduced | Classes in non-exported packages are invisible across modules; `--add-opens`/`--add-exports` workaround | | Java 11 (LTS) | `javax.*` packages removed from JDK (JAXB, JAX-WS, etc.) | Causes `ClassNotFoundException` for `javax.xml.bind.*`, `javax.annotation.*` if not added as explicit dependencies | | Java 16 | Strong encapsulation of JDK internals by default | Reflection on JDK internal classes throws `IllegalAccessError`; use `--add-opens` | | Java 17 (LTS) | Strongly encapsulated JDK internals; no `--illegal-access=permit` | Must use explicit `--add-opens` for each internal package accessed | | Java 21 (LTS) | Virtual threads; no new classloading changes | Same classloading behavior as Java 17 | ## When to Use / When Not to Use | Use This Guide When | Don't Use When | Use Instead | |---|---|---| | `java.lang.ClassNotFoundException` in stack trace | `java.lang.ClassCastException` (class exists, wrong type) | Check for duplicate JARs from different classloaders | | `java.lang.NoClassDefFoundError` in stack trace | `java.lang.UnsupportedClassVersionError` (wrong JDK version) | Recompile with the target JDK or upgrade runtime | | `ExceptionInInitializerError` followed by `NoClassDefFoundError` | `java.lang.OutOfMemoryError: Metaspace` (too many classes loaded) | Java OutOfMemoryError guide | | Class works in IDE but fails in packaged JAR | `java.lang.IncompatibleClassChangeError` (method signature changed) | Rebuild all JARs against same library version | | JDBC `ClassNotFoundException: com.mysql.cj.jdbc.Driver` | `java.sql.SQLException: No suitable driver` (driver exists but URL wrong) | Check JDBC URL format matches driver | ## Important Caveats - **NoClassDefFoundError is permanent per JVM session**: Once the JVM fails to load a class (whether due to missing JAR or failed static initializer), it caches the failure. No amount of retrying in the same JVM process will succeed -- you must fix the issue and restart. [src2, src3] - **ClassNotFoundException message format differs from NoClassDefFoundError**: `ClassNotFoundException` uses dots (`com.example.MyClass`); `NoClassDefFoundError` uses slashes (`com/example/MyClass`). This is because CNFE reports the name as passed to `Class.forName()`, while NCDFE reports the JVM internal name. [src6] - **Application server classloading is non-standard**: Each application server (Tomcat, WildFly, WebSphere, WebLogic) implements its own classloader hierarchy with different parent-first/child-first defaults. Fixes that work for standalone Java may not work in a container. [src4, src5] - **Java 11+ removed Java EE modules from the JDK**: If upgrading from Java 8/9/10, classes like `javax.xml.bind.JAXBContext` and `javax.annotation.PostConstruct` will throw `ClassNotFoundException` unless you add the Jakarta replacements (`jakarta.xml.bind`, `jakarta.annotation`) as explicit dependencies. [src1] ## Related Units - [Java OutOfMemoryError Diagnosis](/software/debugging/java-outofmemoryerror/2026) - [Spring Boot NullPointerException Debugging](/software/debugging/spring-boot-npe/2026)