Spring Boot 2.7.x and Spring Boot 3.0+ are both compatible with Tomcat 10.0.27, but they require different servlet API versions. Spring Boot 2.7 uses the Jakarta EE 9 (formerly javax.servlet) namespace, while Spring Boot 3.0+ uses the Jakarta EE 10 (jakarta.servlet) namespace. You must ensure your application's dependencies align with the correct namespace for the specific Spring Boot version you are running to avoid classpath conflicts or deployment failures in Tomcat 10.
Understanding Servlet API Compatibility
The core issue when pairing Spring Boot with Tomcat 10.0.27 lies in the transition from the Java EE namespace to the Jakarta EE namespace. Tomcat 10 is a Jakarta EE 9 compliant server, meaning it expects applications to use the
jakarta.* package names rather than the older
javax.* names. This shift was mandated by Oracle transferring Java EE to the Eclipse Foundation, which rebranded it as Jakarta EE.
If you attempt to run a standard Spring Boot 2.7 application, which relies on
javax.servlet, against Tomcat 10, you will encounter deployment errors. The container will fail to recognize the servlet mappings because the package names do not match its expectations. Conversely, Spring Boot 3.0+ has been rebuilt to natively support the
jakarta.servlet API, making it the natural fit for Tomcat 10 environments without requiring manual namespace migration.
For developers sticking with Spring Boot 2.7, compatibility requires careful configuration. You cannot simply drop a 2.7 WAR file into Tomcat 10. Instead, you must either upgrade to Spring Boot 3.0 or use a specialized starter that handles the namespace translation. However, the most robust path forward is often evaluating whether staying on 2.7 is necessary, given that it reached end-of-life status. Many teams find that migrating to newer versions resolves these underlying architectural mismatches automatically.
Configuring Spring Boot 2.7 for Tomcat 10
If your project is locked into Spring Boot 2.7.x, you can still deploy it to Tomcat 10.0.27 by explicitly configuring the embedded servlet container or by using a shim layer. The recommended approach involves using the
spring-boot-starter-tomcat dependency with a specific scope or utilizing a third-party library that bridges the gap between
javax and
jakarta.
One common method is to exclude the default embedded Tomcat and rely on the external Tomcat installation entirely. In your
pom.xml, you should set the packaging type to
war and mark the embedded Tomcat dependency as provided. This ensures that the compiled classes use the
javax.servlet APIs, which are then mapped at runtime by the external Tomcat 10 instance if it includes a compatibility layer or if you use a tool like the
tomcat-jakartaee-migration tool to transform the WAR file before deployment.
Alternatively, you can use the
org.apache.tomcat.embed:tomcat-embed-core dependency directly, but this is complex and error-prone. A simpler diagnostic step is to check your build output. If you see errors related to
javax.servlet.http.HttpServlet not being found during the Tomcat startup logs, it confirms a namespace mismatch. You must ensure that the
web.xml or annotation-based configurations correctly reference the
jakarta packages if you have manually migrated them, or stick to
javax only if you are deploying to a Tomcat 9 instance instead.
For detailed guidance on managing dependency conflicts during such migrations, you might find our article on
Upgrading to Spring Boot 3.2 with Spring Security 6.2.0 helpful, as it covers broader compatibility shifts in the Spring ecosystem.
Migrating to Spring Boot 3.0+
The cleanest solution for Tomcat 10.0.27 compatibility is to upgrade to Spring Boot 3.0 or later. Spring Boot 3.0 mandates Java 17 as the baseline and fully embraces the Jakarta EE 10 namespace. When you upgrade, all references to
javax.servlet in your codebase must be changed to
jakarta.servlet. Most modern IDEs offer automated refactoring tools to handle this mass replacement efficiently.
When building a Spring Boot 3.0 application, the embedded Tomcat server defaults to supporting the
jakarta namespace. Therefore, if you run your application locally using
mvn spring-boot:run or deploy the generated JAR/WAR to an external Tomcat 10.0.27 instance, everything works out of the box. There is no need for manual namespace translation because the framework itself generates the correct bytecode.
It is crucial to verify that all third-party libraries you depend on also support Jakarta EE. Libraries that still rely on
javax.servlet will cause classpath collisions. For example, older versions of certain security frameworks or data access tools may not have been updated yet. Always check the release notes of your dependencies after upgrading Spring Boot to ensure they are compatible with the new namespace.
If you encounter connectivity issues during this upgrade process, particularly in containerized environments, refer to
Troubleshooting Java Connect Exception: Connection Refused in Docker Compose Spring Boot Keycloak for insights into network and service discovery problems that often arise during major version transitions.
Docker and Container Deployment Considerations
Deploying Spring Boot applications to Tomcat 10.0.27 within Docker containers introduces additional layers of complexity regarding image sizes and base images. If you are using a multi-stage build, ensure that your final stage pulls a Tomcat 10 base image rather than Tomcat 9. The official Apache Tomcat Docker images provide tags for specific minor versions, such as
tomcat:10.0-jdk17.
When constructing your Dockerfile, you should copy your Spring Boot executable JAR or WAR file into the appropriate directory. For WAR files, place them in the
webapps directory of the Tomcat container. Remember that Tomcat 10 does not serve static content from the root context by default in the same way Tomcat 9 did; you may need to adjust your
server.servlet.context-path property in
application.properties to ensure your endpoints are accessible.
Furthermore, environment variables passed to the container must align with the Spring Boot profile system. If you are using Kubernetes or Docker Compose, ensure that health checks point to the correct actuator endpoints. Misconfigured health checks can lead to false negatives if the servlet mapping is slightly off due to namespace confusion. Always test your containerized deployment in a staging environment that mirrors production Tomcat 10.0.27 configurations before pushing to live systems.
For broader troubleshooting on website connectivity in self-hosted environments, see
Troubleshooting Self-Hosted Website Connectivity Issues.
Frequently Asked Questions
Can I run Spring Boot 2.7 directly on Tomcat 10 without changes?
No, you cannot run a standard Spring Boot 2.7 application directly on Tomcat 10 because it uses the
javax.servlet API, which Tomcat 10 does not support. You must either migrate the code to use
jakarta.servlet or use a migration tool to transform the WAR file before deployment.
What is the minimum Java version required for Spring Boot 3.0?
Spring Boot 3.0 requires Java 17 or higher as its baseline version. This requirement is tied to the adoption of Jakarta EE 10 features and modern language enhancements that simplify development and improve performance.
How do I check if my third-party libraries are compatible with Jakarta EE?
You should review the release notes and documentation of each dependency to confirm they support the
jakarta.* namespace. Often, libraries released after mid-2022 include Jakarta-compatible artifacts, while older versions may only offer
javax variants.
Does Tomcat 10.0.27 support legacy Java EE 8 applications?
Tomcat 10 is strictly a Jakarta EE 9 server and does not support legacy Java EE 8 (
javax) applications natively. To run old applications, you would need to use Tomcat 9 or apply a namespace migration tool to convert the application code and resources.
Why am I getting a ClassNotFoundException for HttpServlet after upgrading?
This error typically indicates that your application code still references
javax.servlet.http.HttpServlet while running on a Tomcat 10 instance expecting
jakarta.servlet.http.HttpServlet. You must update your import statements and any custom servlet implementations to use the Jakarta namespace.