From Java EE to Jakarta EE the Namespace Change Explained
Why javax became jakarta, which packages moved and which did not, who is affected and how the change shows up in Spring Boot 3 and application servers.

Few changes in Java have caused as many broken builds as a renamed package prefix. The rename is simple to describe and wide in effect. This post explains why it happened, which packages changed and what that means in practice. The error that results from it is in javax to jakarta ClassNotFoundException, and the platform is explained in what Jakarta EE is.
Why the names changed
Oracle donated the Java EE technologies to the Eclipse Foundation in 2017 and kept the Java trademark and, importantly, the javax namespace. The agreement allowed the Eclipse Foundation to evolve the specifications, and did not allow it to make incompatible changes to anything under javax. After Jakarta EE 8 repeated Java EE 8 under the new owner, the community decided to start evolving the APIs, and doing so required leaving the javax namespace behind. Jakarta EE 9 was the planned single break.
What changed
Every API that belongs to the platform changed prefix:
| Before | After |
|---|---|
javax.servlet.* | jakarta.servlet.* |
javax.persistence.* | jakarta.persistence.* |
javax.validation.* | jakarta.validation.* |
javax.ws.rs.* | jakarta.ws.rs.* |
javax.inject.* | jakarta.inject.* |
javax.annotation.* | jakarta.annotation.* |
javax.enterprise.* | jakarta.enterprise.* |
javax.faces.* | jakarta.faces.* |
Jakarta EE 9 changed names only. Behavior and APIs stayed the same, so migration is a rename plus dependency updates.
Source code shows it directly:
// Jakarta EE 8 and earlier
import javax.servlet.http.HttpServletRequest;
import javax.persistence.Entity;
// Jakarta EE 9 and later
import jakarta.servlet.http.HttpServletRequest;
import jakarta.persistence.Entity;What did not change
The JDK has javax packages of its own that are part of Java SE. They are not Jakarta EE and kept their names: javax.sql, javax.crypto, javax.net, javax.naming, javax.security.auth, javax.xml.parsers and javax.swing, among others. A global find and replace on javax. breaks those. Migrating by hand has the safe list.
Strings and configuration also carry names: XML namespaces in web.xml and persistence.xml, class names in reflection and META-INF/services files all need the new prefix.
Who is affected
| You use | Effect |
|---|---|
| Spring Boot 2.x | No change; stays on javax |
| Spring Boot 3 and later | Requires jakarta; libraries must be Jakarta-ready |
| Tomcat 9 | javax; Tomcat 10 and later use jakarta |
| An application server | Choose a Jakarta EE 9 or later release for jakarta |
A library with javax imports | Needs a release built for jakarta or a transformation |
Spring Boot 3 was the large wave: millions of projects had to move because the framework did. If your application uses Spring Boot 3, you already write jakarta.persistence.Entity.
How to migrate
For code you own, an automated recipe does most of the work: migrating with OpenRewrite. For binaries you cannot rebuild, the Eclipse Transformer rewrites jars. The leftover cases are in migrating by hand.
Which Jakarta EE version matches which API versions
The rename arrived with Jakarta EE 9, and later releases moved the APIs forward under the new names. When a library asks for "Jakarta Servlet 6", this is the platform it belongs to:
| Jakarta EE | Servlet | Persistence | Needs Java SE |
|---|---|---|---|
| 8 | 4.0 (javax) | 2.2 (javax) | 8 |
| 9 and 9.1 | 5.0 (jakarta) | 3.0 (jakarta) | 8 for 9, 11 for 9.1 |
| 10 | 6.0 | 3.1 | 11 |
| 11 | 6.1 | 3.2 | 17 |
Version 8 is the last release with javax. Anything labelled Servlet 4 or Persistence 2.2 is on the old side of the line, whatever the product around it is called. Tomcat 10.0 and 10.1, Jetty 11 and later, Hibernate ORM 6 and later and Spring Framework 6 and later all live on the jakarta side.
Find out which side a dependency is on
Reading the imports is slow when the dependency is a jar. Look inside it instead:
unzip -l lib/some-library.jar | grep -E 'javax/(servlet|persistence|validation)' | head
unzip -l lib/some-library.jar | grep -E 'jakarta/(servlet|persistence|validation)' | headA jar that lists classes under javax/servlet was compiled against the old API, and one that references those packages inside its bytecode needs the same. The JDK's jdeps shows the referenced packages for a jar without unpacking it:
jdeps -verbose:package some-library.jar | grep -E 'javax\.(servlet|persistence)'Run it over the whole lib directory of a WAR before deciding on a migration path. A short list of offenders is a different project from a long one.
A mixed classpath fails in a confusing way
Putting a javax library into a jakarta application rarely fails at startup. The class loads, the annotation is present, and nothing happens, because the container looks for jakarta.persistence.Entity and the class carries javax.persistence.Entity. The symptoms are an entity that is not recognised, a servlet filter that never runs, or a validation constraint that is never applied. Only the direct calls fail loudly, with ClassNotFoundException or NoSuchMethodError. That makes silence the worst outcome, and it is why a migration needs a check that every annotation was recognised, not only a build that compiles.
Descriptors and strings
Source imports are the visible part. The descriptors need the same change, and a compiler will not point them out:
<!-- Jakarta EE 8 -->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="4.0">
<!-- Jakarta EE 10 -->
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" version="6.0">Persistence properties that name a provider class are strings as well, and so are META-INF/services files, which list implementations by fully qualified name. A search for javax. across src/main/resources finds them. Keep the JDK packages from the previous section out of the replacement, or javax.net.ssl.trustStore in a properties file stops meaning anything.
The effect on teaching material and answers
Older posts, answers and books use javax everywhere, and the code in them is correct for the platform at the time. Copy it into a Spring Boot 3 or later project and the imports fail. Change the prefix for the APIs in the table above, and leave the JDK ones alone.
Teaching the team the rule
Once the migration is finished, the rename still shows up in daily work: in copied answers, in generated code and in new hires' first pull requests. A one-line rule in the contributing guide covers it: use jakarta for Servlet, Persistence, Validation, REST and CDI, and javax only for the JDK packages that Java SE itself defines. Add a build check that fails on javax.servlet, javax.persistence and the other renamed packages, so a pasted import is caught at once.
A short grep in CI is enough. It costs nothing to maintain, and it prevents the slow return of the old names that happens when examples from older sources are pasted into a new codebase.
Where the rename does not matter
If you stay on Spring Boot 2 and Tomcat 9 and have no plan to upgrade, you never see it, although security support for those lines is ending, which forces the move eventually. For Spring-specific upgrade steps see Spring Boot from first project to production. The Jakarta EE 9 release page and the Eclipse Transformer project are the primary sources.


