NoClassDefFoundError: com/devinhyderabad/pay/PaymentGateway

Q: Close the compile-time vs runtime classpath drift

When to use: Use this when the app compiled fine but dies at startup or on first use after deployment.. The class was on the compile classpath but is absent from the runtime one. Typical sources: a dependency marked provided, an exclusion added to shade/repackage plugins, a server whose shared lib dir lacks the jar, or deploying stale artifacts. Compare both classpaths explicitly and fix the pipeline, not the symptom.

Q: Could not initialize class X — chase the earlier ExceptionInInitializerError

When to use: Use this when the message reads NoClassDefFoundError: Could not initialize class com.example.Foo with NO Caused by section.. That variant means the class WAS found but its static initializer threw on first use. The JVM marks the class as failed and every later touch gets this bare NCDE. Scroll up in the log: the very first occurrence shows the real ExceptionInInitializerError with the true root cause (missing config, DB down during init). Fix that original error.

Q: (wrong name: ...) — package statement vs directory mismatch

When to use: Use this when the Caused by says something like wrong name: com/example/Foo.. You ran a .class file directly from the wrong working directory, or the folder layout does not match its package declaration. The loader defines the class under one name while the constant pool asks for another. Always compile with javac -d and launch the fully-qualified name from the package root.

Q: Verify shipping artifacts in CI before they deploy

When to use: Use this to stop recurrence across services rather than fixing one incident.. A startup smoke test catches drift the moment it appears: boot the packaged artifact, assert the critical classes resolve, fail the build otherwise. jdeps adds static reachability checks for plain jars.

Q: Reconcile multi-module deployments where jar versions drift

When to use: Use this in monorepos or multi-module builds where only some module jars were redeployed.. After a refactor, the class exists somewhere on the classpath but under a different package, or inside sibling jars pinned at older versions — callers resolve against stale constant pools asking for names the deployed jars no longer contain. Ship one consistent artifact set: manage versions centrally in the parent POM / BOM and rebuild all modules together instead of hand-patching individual jars in production lib directories.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

Exception in thread "main" java.lang.NoClassDefFoundError: com/devinhyderabad/pay/PaymentGateway
	at com.devinhyderabad.pay.NcdefMain.main(NcdefMain.java:5)
Caused by: java.lang.ClassNotFoundException: com.devinhyderabad.pay.PaymentGateway
	at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:580)
	at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:490)
	... 1 more

⚡ Quick Fix Works 80% of the time

Make the runtime classpath match what you compiled against — rebuild the artifact so the missing class actually ships.

mvn clean package
# Verify the class really is inside the artifact you deploy:
jar tf target/app.jar | grep PaymentGateway

🧠 Why this Happens

Tap to expand the deep technical explanation

Resolution of a class reference is lazy: the constant-pool entry for PaymentGateway stays symbolic until the first active use — executing new, calling a static method, or touching a static field. At that moment the JVM asks the defining loader to resolve and link the name (stored internally in slash form, com/devinhyderabad/pay/PaymentGateway). When the loader reports ClassNotFoundException because no URL defines it, the JVM is mid-linking, not mid-user-call, so per the specification it must raise an Error — NoClassDefFoundError — and attaches the loader exception as its cause, producing the Caused by chain. Because the JVM caches negative resolution per classloader state, once it fails it keeps failing even after you drop the correct jar onto a running process.

The HITEC City Parking Spot Analogy:

You met your contact at their office last week — compile time. Today the office is empty and the company directory got reprinted — the runtime classpath changed. The security desk (classloader) shrugs: the plan they were handed simply does not list this person.

🔁 How to Reproduce Confirm this is your error

Compile NcdefMain together with PaymentGateway, delete out_ncdef/com/devinhyderabad/pay/PaymentGateway.class, then run java -cp out_ncdef com.devinhyderabad.pay.NcdefMain. Resolution of new PaymentGateway() happens at first active use, fails, and HotSpot wraps the underlying CNFE as the cause. (Lab capture: OpenJDK 25.)

🛠️ Solutions (5 Ways to Fix)

Solution 1✓ Most common cause

Close the compile-time vs runtime classpath drift

👉 Use this when the app compiled fine but dies at startup or on first use after deployment.

The class was on the compile classpath but is absent from the runtime one. Typical sources: a dependency marked provided, an exclusion added to shade/repackage plugins, a server whose shared lib dir lacks the jar, or deploying stale artifacts. Compare both classpaths explicitly and fix the pipeline, not the symptom.

mvn dependency:tree -Dscope=runtime > runtime.txt
grep devinhyderabad runtime.txt

# Spring Boot: confirm the nested lib shipped
unzip -l target/app.jar | grep PaymentGateway

# Plain classpath runs: print what the JVM actually sees
java -cp app.jar com.devinhyderabad.pay.Main -verbose:class 2>&1 | head

Solution 2

Could not initialize class X — chase the earlier ExceptionInInitializerError

👉 Use this when the message reads NoClassDefFoundError: Could not initialize class com.example.Foo with NO Caused by section.

That variant means the class WAS found but its static initializer threw on first use. The JVM marks the class as failed and every later touch gets this bare NCDE. Scroll up in the log: the very first occurrence shows the real ExceptionInInitializerError with the true root cause (missing config, DB down during init). Fix that original error.

// Defensive static init: log the real cause immediately
private static final Gateway GATEWAY = createGateway();

private static Gateway createGateway() {
    try {
        return new Gateway(config.endpoint());
    } catch (RuntimeException e) {
        throw new IllegalStateException("Gateway init failed", e); // keeps context visible
    }
}

Solution 3

(wrong name: ...) — package statement vs directory mismatch

👉 Use this when the Caused by says something like wrong name: com/example/Foo.

You ran a .class file directly from the wrong working directory, or the folder layout does not match its package declaration. The loader defines the class under one name while the constant pool asks for another. Always compile with javac -d and launch the fully-qualified name from the package root.

javac -d out src/com/devinhyderabad/pay/Main.java
cd out  # package root, NOT the folder holding Main.class
java com.devinhyderabad.pay.Main

Solution 4

Verify shipping artifacts in CI before they deploy

👉 Use this to stop recurrence across services rather than fixing one incident.

A startup smoke test catches drift the moment it appears: boot the packaged artifact, assert the critical classes resolve, fail the build otherwise. jdeps adds static reachability checks for plain jars.

# CI gate: artifact must contain the class AND start
jar tf app.jar | grep -q com/devinhyderabad/pay/PaymentGateway || exit 1
jdeps --multi-release 17 --print-module-deps app.jar

Solution 5

Reconcile multi-module deployments where jar versions drift

👉 Use this in monorepos or multi-module builds where only some module jars were redeployed.

After a refactor, the class exists somewhere on the classpath but under a different package, or inside sibling jars pinned at older versions — callers resolve against stale constant pools asking for names the deployed jars no longer contain. Ship one consistent artifact set: manage versions centrally in the parent POM / BOM and rebuild all modules together instead of hand-patching individual jars in production lib directories.

# Do sibling modules disagree on resolved versions?
mvn dependency:tree -Dincludes=com.devinhyderabad:* \
    -pl services/api,services/worker

# Fix at the source: single version owner (parent <dependencyManagement>),
# then rebuild and deploy ALL modules as one release:
mvn clean deploy -DskipTests

📋 Version Notes

Java 8

Classic era of this error: WEB-INF/lib drift in wars and hand-managed -cp lists. AppClassLoader behavior identical to today.

Java 11

Module system can hide packages entirely — split-package conflicts surface as different LinkageErrors (e.g. IllegalAccessError) rather than NCDE.

Java 17

Strong encapsulation (JEP 396/403) blocks reflective access to JDK internals, but application-level NCDE semantics are unchanged.

Java 21

Identical linkage behavior; virtual threads do not participate in class loading.

🛡️ How to Prevent This Next Time

Build one reproducible artifact in CI and deploy exactly that file, run a startup smoke test that touches every critical class, pin transitive dependency versions, and never hand-edit production classpaths.