Symptoms & Diagnosis
The java.lang.NoSuchMethodError in Java 21 usually occurs when there is a mismatch between the version used to compile the code and the version used to run it. With the introduction of Sequenced Collections (JEP 431), several core interfaces like List, Deque, and Set received new methods such as reversed(), getFirst(), and getLast().
You will typically see this error in your logs during application startup or when executing a specific collection-based operation. The stack trace often points to a method that seems to exist in the source code but cannot be found by the Java Virtual Machine (JVM) at runtime.
| Symptom | Common Message Snippet | Primary Cause |
|---|---|---|
| Runtime Crash | java.lang.NoSuchMethodError: ‘java.util.SequencedCollection java.util.List.reversed()’ | Binary incompatibility between Java 21 and older JREs. |
| Dependency Conflict | NoSuchMethodError at [Third-party Library] | Outdated libraries (like Lombok) that manipulate bytecode. |
| Build Failure | Method not found during testing | Mismatched Maven/Gradle compiler vs runtime settings. |
To diagnose this, check your runtime environment immediately. Run the following command in your terminal to verify which version of Java is actually executing your application:
java -version
Troubleshooting Guide
The most common cause is compiling your project with Java 21 while running it on an older Java version (like 17 or 11). Since SequencedCollection did not exist in those versions, the JVM throws an error when it tries to link the method call.
Step 1: Synchronize Java Versions
Ensure that your JAVA_HOME environment variable and your IDE settings match. If you use Maven, ensure your maven-compiler-plugin target is consistent with your execution environment.
# Example: Setting JAVA_HOME to Java 21 on Unix
export JAVA_HOME=/path/to/jdk-21
export PATH=$JAVA_HOME/bin:$PATHStep 2: Update Bytecode Manipulators
If you use Lombok, MapStruct, or Hibernate, these libraries often generate or modify bytecode. Older versions of Lombok (prior to 1.18.30) are known to cause NoSuchMethodError when encountering Java 21’s new collection hierarchy.
Update your pom.xml or build.gradle to the latest version of these tools to ensure they recognize the new interface inheritance chains.
Step 3: Clean and Rebuild
Sometimes, stale artifacts in your target or build folder contain old references. A fresh build often resolves linking issues that persist after a version upgrade.
# For Maven users
mvn clean install
# For Gradle users
./gradlew clean buildPrevention
To prevent this error in the future, implement strict version gating in your CI/CD pipeline. Use a .sdkmanrc file or a .java-version file to ensure every developer on the team uses the exact same JDK distribution.
Avoid using “preview features” in production environments unless your runtime is explicitly configured to support them. Always verify that your container images (like Docker) are pulling the openjdk:21 or eclipse-temurin:21 tags rather than relying on a generic latest tag.
Finally, utilize the --release flag in your compiler options. This flag ensures that the code is compiled against the signature of the target Java version, catching potential NoSuchMethodError issues at compile time rather than runtime.