The javax to jakarta namespace change is one of the most mechanical parts of an AEM LTS migration, but it is also the one most likely to be done incompletely, since the code will often still compile against a mixed namespace state.
What actually changes
Servlet APIs (javax.servlet.*) move to jakarta.servlet.*, along with related specs your custom code may touch: Jakarta Mail, Jakarta Annotations, and in some cases JCR-adjacent utility classes that historically lived under javax. AEM's own OSGi bundles are updated for you — the risk is entirely in your custom servlets, filters, and any library wrapping the Servlet API.
A safe migration order
- Grep the codebase for every
javax.servlet,javax.mailand related import before touching anything, so you have a real inventory rather than fixing errors reactively - Update imports package by package rather than with a blind find-and-replace across the whole repo — some third-party dependencies may still expect the old namespace
- Check custom
FilterandServletimplementations first; these are the most common compile break point - Rebuild and watch for OSGi package import mismatches, not just compiler errors — a bundle can compile fine and still fail to resolve if it imports a package version range that no longer matches
Third-party library risk
The highest-risk dependency in most AEM projects is an older PDF, image, or reporting library that has not published a jakarta-compatible release. In that case you are choosing between a library upgrade, a fork, or an adapter shim — plan this decision early, since it can affect the migration timeline more than the AEM upgrade itself.
Verification
After the namespace change, do not rely on a clean compile as proof of correctness. Deploy to a scratch instance and specifically exercise every custom servlet endpoint and filter chain — namespace mismatches sometimes manifest only as a silent 404 or a filter that never triggers, rather than a startup error.