java.lang.NoClassDefFoundError
ID: java/no-class-def-found
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 17 | active | — | — | — |
Root Cause
NoClassDefFoundError means the JVM found the class at compile time but cannot find it at runtime. Different from ClassNotFoundException — this indicates the class was available during compilation but is missing from the runtime classpath, often due to a failed static initializer or missing transitive dependency.
genericWorkarounds
-
85% success Check for a failed static initializer that may have caused the class to be marked as unavailable
1. Look for an earlier ExceptionInInitializerError in the logs — this is the root cause. 2. NoClassDefFoundError for a class whose static initializer previously failed will repeat on every access attempt. 3. Fix the static initializer (e.g., fix the static field initialization, resource loading, or configuration parsing that failed). 4. Restart the JVM — the class cannot be recovered in the same JVM instance.
-
88% success Verify the JAR containing the class is on the runtime classpath
1. Convert the class name in the error from 'com/example/MyClass' to 'com.example.MyClass'. 2. Search for which JAR contains it: 'grep -rl MyClass.class lib/' or check Maven Central. 3. Ensure that JAR is in the runtime classpath. 4. Check Maven/Gradle scopes — 'provided' scope means the JAR must be supplied by the runtime environment. 5. In fat/uber JARs, ensure the shade plugin is not excluding the needed classes.
Dead Ends
Common approaches that don't work:
-
Adding the class to the source code assuming it is missing
80% fail
NoClassDefFoundError usually means a compiled .class file or JAR is missing from the runtime classpath, not from the source code. The class compiled successfully but is not available at runtime.
-
Catching NoClassDefFoundError and providing a fallback implementation
70% fail
NoClassDefFoundError is an Error, not an Exception. While it can be caught, the missing class likely means a critical component is unavailable. Fallback implementations rarely provide equivalent functionality and mask the deployment issue.