Migrate javax to jakarta by Hand and What the Tools Miss
Which javax packages to rename and which to leave, the places automated tools miss such as strings and descriptors, and how to verify a manual migration.

Even with an automated recipe, someone has to know what the tool misses. This post is the manual procedure and a list of the places where migrations fail late. It pairs with migrating with OpenRewrite, which does most of steps 1 to 3 for you. The background is in the namespace change explained.
Step 1: rename the Jakarta packages
Rename these and leave the rest:
Rename javax. to jakarta. | Do not rename |
|---|---|
servlet, persistence, validation | sql, crypto, net |
ws.rs, json, jms | naming, security.auth |
inject, enterprise, interceptor | xml.parsers, xml.transform, xml.xpath |
annotation (PostConstruct, Resource) | swing, imageio, management |
faces, el, mail, transaction, websocket, ejb | script, tools, lang.model |
Two special cases: javax.annotation.processing is part of the JDK and stays javax; javax.xml.bind (JAXB) and javax.xml.ws became jakarta.xml.bind and jakarta.xml.ws, though the JDK had already removed them. Apply the rename with your IDE's refactoring on a package list, not with a blind regular expression.
Step 2: dependencies
Update the artifacts to their Jakarta forms and versions:
<!-- before -->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>4.0.1</version>
</dependency>
<!-- after -->
<dependency>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>6.0.0</version>
<scope>provided</scope>
</dependency>Frameworks move as a set: Hibernate 6 or later, Hibernate Validator 8, Spring Framework 6 or later, Jersey 3. Check each against the Jakarta release it targets. Mixing a Hibernate 5 with jakarta.persistence fails at runtime.
Step 3: descriptors and configuration
<!-- before -->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="4.0">
<!-- after -->
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" version="6.0">Do the same for persistence.xml, beans.xml, faces-config.xml and any Hibernate or other configuration that names classes. Facelets tag library namespaces change from http://xmlns.jcp.org/jsf/html to jakarta.faces.html.
Where tools miss things
| Place | Why a tool misses it |
|---|---|
| String literals with class names | Class.forName("javax.servlet.Filter") is data to a compiler |
META-INF/services/javax.* files | The file name itself is the old name |
| Annotations processed at build time | Processor output lives in target/generated |
| Native-image and reflection configuration | JSON files with class names |
| Properties and YAML | spring.factories, logging configuration |
| Shaded or uber jars | The old classes are inside another jar |
| Documentation and scripts | Deployment scripts that name packages |
Search for each:
grep -rn "javax\.\(servlet\|persistence\|validation\|ws\|inject\|annotation\|faces\)" src --include="*"
find . -path ./target -prune -o -name "javax.*" -printStep 4: regenerate
Code generated from schemas (JAXB classes, OpenAPI clients, JPA metamodel) must be regenerated by tools that emit jakarta. Upgrade the generator plugin and rebuild; never hand-edit the output.
Step 5: verify
- Compile cleanly with no references to the old API.
- Run the unit tests.
- Start the application on a Jakarta runtime and exercise the main paths, including startup, because many failures only appear at class loading.
- Check the dependency tree for any artifact still pulling
javax.*:./mvnw dependency:tree | grep "javax[.]". A transitive old API is the most common leftover; its error looks like the ClassNotFoundException fix.
Which javax packages to rename, and which to keep
The first mistake in a manual migration is a global search and replace of javax. with jakarta.. Many javax packages belong to the JDK and did not move. A scan separates them. This sample servlet imports from ten packages.
grep -rhoE "javax\.[a-z]+" src web.xml | sort | uniq -c | sort -rn 1 javax.xml
1 javax.validation
1 javax.sql
1 javax.servlet
1 javax.persistence
1 javax.net
1 javax.inject
1 javax.faces
1 javax.cryptojavax.servlet, javax.persistence, javax.inject, javax.validation and javax.faces are Jakarta EE and must change. javax.sql, javax.net and javax.crypto are JDK APIs and must not. javax.xml is both: javax.xml.bind (JAXB) moved to jakarta.xml.bind, while javax.xml.parsers and javax.xml.transform are JDK. That is why the replacement must name the packages. This perl command renames only the Jakarta ones, and the result below is from the run on the sample.
perl -pi -e 's/\bjavax\.(servlet|persistence|inject|validation|xml\.bind|faces|ejb|jms|ws\.rs|annotation|transaction|mail|enterprise)\b/jakarta.$1/g' $(grep -rl "javax\." src web.xml)<context-param><param-name>jakarta.faces.PROJECT_STAGE</param-name>...
import jakarta.servlet.http.HttpServlet;
import jakarta.persistence.Entity;
import jakarta.inject.Inject;
import jakarta.validation.constraints.NotNull;
import jakarta.xml.bind.annotation.XmlRootElement;
import javax.sql.DataSource;
import javax.net.ssl.SSLContext;
import javax.crypto.Cipher;The Jakarta imports changed, the three JDK imports stayed. Note javax.annotation is a trap in the list: javax.annotation.PostConstruct and Resource moved to jakarta.annotation, but javax.annotation.processing is a JDK package, so extend the regular expression with care and scan afterwards. One caution about the pattern: javax.transaction renames the JTA package, but javax.transaction.xa is part of the JDK in the java.transaction.xa module, so check imports of XAResource and Xid by hand.
The descriptor namespaces are not in javax.
The command above did not touch web.xml's namespace, and that is a second class of change. XML descriptors declare a schema, and containers that implement Jakarta EE 9 and later expect the new one.
<!-- before -->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="4.0">
<!-- after, for Servlet 6.0 on Jakarta EE 10 -->
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" version="6.0">The same applies to persistence.xml (https://jakarta.ee/xml/ns/persistence, version 3.0 or later), beans.xml, faces-config.xml and ejb-jar.xml. A container that ignores a descriptor with the old namespace may not complain; the symptom is a listener or a persistence unit that silently never loads. Also check service files under META-INF/services/: a file named javax.persistence.spi.PersistenceProvider must be renamed jakarta.persistence.spi.PersistenceProvider, since the file name is the interface name.
find src -path '*META-INF/services/javax.*'
grep -rn 'xmlns.jcp.org\|java.sun.com/xml/ns' srcDependencies are the long pole
Every library compiled against javax needs a release compiled against jakarta, or it throws NoClassDefFoundError: javax/servlet/Filter when it meets the new classes. List which of your dependencies have such a release, and replace those that do not. A transformer can rewrite a binary jar if no release exists, but treat that as a bridge.
mvn dependency:tree | grep -E 'hibernate|jersey|resteasy|jackson-jaxrs|primefaces|myfaces|mojarra|weld'
jdeps --multi-release 17 -verbose:class -cp 'target/lib/*' target/classes | grep 'javax\.\(servlet\|persistence\|inject\)' | headThe second command shows which classes still reference the old packages after your own code has moved, and points at the jars that need to change. Updating the framework first (Spring Framework 6 or Boot 3, Hibernate 6, Jersey 3, PrimeFaces with the jakarta classifier) usually pulls most of them along.
Verify with the runtime, not only the compiler
A clean compile means the names resolve. Deploy to the target server and exercise a request that touches each technology: a servlet, a JPA query, a bean injection, a validation failure, a JSF page. Watch the server log during startup for descriptor warnings. Keep a list of the checks in the pull request so a reviewer can repeat them, and run the full test suite with the Jakarta server in CI. Where an automated tool such as OpenRewrite's Jakarta recipe or Eclipse Transformer is available, run it as well, then compare its result with the manual scan: differences show what each approach misses.
Plan the migration as a series of small merges
A large rename in one commit is hard to review and harder to revert. Split it. First merge the dependency upgrades that work with both names where possible, such as libraries that publish both a javax and a jakarta artifact. Then merge the rename of the application's own imports by module, so each pull request touches one area and can be tested alone. Then merge the descriptor and configuration changes. Keep the server upgrade last or first, whichever your environments allow, but never in the same change as the rename, so that a failure can be assigned to one of them.
Agree a freeze on new code that uses javax imports once the rename starts, and add a check to the build that fails when one appears. A one-line grep in the pipeline is enough, and it prevents the migration from being undone by a branch that was created before it began.
Where a manual migration is not worth it
A project with thousands of files should use a recipe and review the diff. A manual rename is sensible for a handful of files, a library you maintain or a learning exercise. The Jakarta EE 9 specification overview lists every renamed API, and the Eclipse Transformer handles binaries.


