Java: error: invalid target release: 21

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# What is the build actually using?
mvn -version
java -version
echo $JAVA_HOME

# Point it at a JDK new enough for the target
export JAVA_HOME=$(/usr/libexec/java_home -v 21)   # macOS
sudo update-alternatives --config java             # Debian, Ubuntu

# Pin the target in the project so CI cannot drift
<properties><maven.compiler.release>21</maven.compiler.release></properties>

# Gradle can find or download a matching toolchain itself
java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }

# CI: set the JDK in the workflow rather than trusting the image default
# actions/setup-java@v4 with java-version: '21'

How to diagnose Java errors

Java errors concentrate at the class loading boundary (ClassNotFoundException, NoClassDefFoundError, UnsupportedClassVersionError) and around resource pools under load. Class loading errors are almost always classpath or version problems rather than missing code. UnsupportedClassVersionError in particular is a pure bytecode-version mismatch and tells you exactly which JDK compiled the class.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Print the actual runtime version with java -version and compare it against your build target. Major bytecode version 65 is Java 21, 61 is Java 17, 52 is Java 8.
2. Inspect the resolved dependency tree (mvn dependency:tree, gradle dependencies) to find duplicate or conflicting versions of the same library.
3. For pool exhaustion, log pool metrics (HikariCP exposes active, idle and pending counts). Exhaustion means connections are not being returned, which is a try-with-resources problem.
4. Enable -verbose:class temporarily to see which jar a class is loaded from when two versions are on the classpath.
5. Capture a heap dump on OOM with -XX:+HeapDumpOnOutOfMemoryError and analyse it rather than raising -Xmx blindly.

Tools worth reaching for

• mvn dependency:tree
• jcmd / jstack / jmap
• -verbose:class
• Eclipse MAT
• JFR (Java Flight Recorder)

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 maven.apache.org

Related Java errors

• Cannot get a connection, pool errorThe database connection pool (HikariCP, DBCP, etc.) has no available connections. All…
• ClassCastExceptionAn object was cast to a type it is not an instance of. Common when using raw types or…
• ConcurrentModificationExceptionA collection was modified while being iterated over. This can happen in single-threaded code…
• Could not resolve dependenciesMaven or Gradle cannot download or resolve project dependencies. May be caused by missing…
• Java: Cannot invoke "String.length()" because "s" is nullThis is a helpful NullPointerException message, on by default since Java 15, and it names the…
• Java: java.lang.OutOfMemoryError: Java heap spaceThe heap could not satisfy an allocation after a full collection. Raising -Xmx only helps…
• Java: java.lang.OutOfMemoryError: MetaspaceMetaspace holds class metadata rather than objects, so raising the heap changes nothing. It…
• Java: NoClassDefFoundError: Could not initialize class XThis is not a missing class. The class was found, its static initialiser ran and threw, and…

See all 19 Java errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.