Java "NoClassDefFoundError" - Fix Classpath/Init Errors in CI

NoClassDefFoundError means the class existed when you compiled but is absent (or failed to initialize) at runtime. It is a classpath/packaging problem, not a typo -- the compiler was satisfied; the runtime was not.

What this error means

The app or tests throw java.lang.NoClassDefFoundError: com/example/Foo, sometimes phrased as Could not initialize class com.example.Foo. It is deterministic for a given build artifact -- the jar or classpath is simply missing the class or a transitive dependency.

Exception in thread "main" java.lang.NoClassDefFoundError: org/example/Helper
	at com.example.App.main(App.java:14)
Caused by: java.lang.ClassNotFoundException: org.example.Helper

Common causes

Dependency missing from the runtime classpath

A library on the compile classpath was not packaged into the runnable jar or not put on the runtime classpath, so the class cannot be loaded when the JVM reaches it.

Static initializer failed

When the variant is Could not initialize class, a static block or static field threw on first load. The class exists but cannot be used because initialization aborted.

How to fix it

Put the missing class on the runtime classpath

1. Confirm the dependency is declared at runtime scope (not just compileOnly/provided).
2. For a fat jar, ensure the shade/assembly plugin actually bundles the dependency.
3. Print the effective runtime classpath and verify the missing artifact is present.

mvn dependency:tree
java -cp "app.jar:libs/*" com.example.App

Fix a failed static initializer

1. Look for Caused by: under the first failure -- the original static-init exception is the real cause.
2. Fix what the static block depends on (a missing resource, config, or env value).
3. Re-run; once initialization succeeds the class loads normally.

How to prevent it

• Keep runtime and compile classpaths consistent; do not mark needed deps provided.
• Verify fat-jar packaging includes every runtime dependency.
• Avoid risky work in static initializers that can fail under CI conditions.

Related guides