Spring Boot application gives 404 when deployed to Tomcat but works with embedded server

If your Spring Boot application works flawlessly with the embedded server but throws a 404 Not Found error when deployed to an external Tomcat server, you’re not alone! This issue is common and can arise from various configuration mismatches or deployment quirks. In this post, we’ll explore several solutions to resolve this problem.

Why the 404 Error Happens

When deployed to an external servlet container like Apache Tomcat, Spring Boot applications must be properly configured to initialize and run within the container’s environment. Common issues include:

Missing or incorrect initialization (SpringBootServletInitializer).
Compatibility issues with Tomcat versions (e.g., Tomcat 10+).
Incorrect context paths or dependencies.

Let’s dive into proven solutions.

Solution 1: Extend SpringBootServletInitializer

Spring Boot applications need to extend SpringBootServletInitializer and override the configure method to be deployable as a WAR file. Without this, the application won’t initialize correctly in an external Tomcat server.

Here’s the corrected Application.java file:

@SpringBootApplication
public class Application extends SpringBootServletInitializer {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(Application.class);
    }
}

Make sure your pom.xml is configured to package the application as a WAR file:

<packaging>war</packaging>

Hat Tip: This solution was highlighted in mtdevuk’s blog post.

Solution 2: Compatibility with Tomcat Versions

If you’re deploying to Tomcat 10 or higher, note that Spring Boot does not support the Jakarta Servlet 5.0+ APIs used by Tomcat 10.

Fix: Use Tomcat 9 or Lower

Downgrade your Tomcat version to 9.
Alternatively, ensure your application is compatible with Tomcat 10 by migrating to Spring Framework 6+ and Spring Boot 3+, which support the Jakarta EE namespace.

References:

Solution 3: Context Path Configuration

When deployed to an external Tomcat, your application may default to a context path derived from the WAR filename (e.g., /your-app-name). If your application expects to be served at /, a 404 error occurs.

Fix: Set the Context Path Explicitly

Add the following to application.properties:

server.servlet.context-path=/

Alternatively, rename the WAR file to ROOT.war to serve it from the root context.

Solution 4: Dependency Conflicts

Certain plugins or dependencies may interfere with the WAR file’s deployment. For example, the maven-dependency-plugin can sometimes cause issues.

Fix: Remove Maven Dependency Plugin

Comment out or remove the following section from your pom.xml:

<!--
<plugin>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>3.3.0</version>
</plugin>
-->

This solution has resolved deployment issues for many users.

Solution 5: Debugging Deployment Logs

Check the Tomcat logs (e.g., catalina.out) for initialization errors. Common issues include:

Missing or misconfigured dependencies.
Errors in @Controller or @RequestMapping.

Fix: Enable Debug Logs

Update application.properties to log debugging information:

logging.level.org.springframework=DEBUG

Analyze the logs to pinpoint issues during startup.

Conclusion

Deploying a Spring Boot application as a WAR file to Tomcat requires extra attention to configuration details. By following these solutions, you can eliminate 404 errors and ensure smooth deployment.

Summary of Solutions:

Extend SpringBootServletInitializer in Application.java.
Use Tomcat 9 or downgrade if using Tomcat 10+.
Configure the correct context path.
Remove conflicting Maven plugins.
Debug deployment logs for hidden issues.

Still facing issues? Let us know in the comments with specific error logs for personalized help!

Keywords: Spring Boot WAR deployment, Tomcat 404 error, SpringBootServletInitializer, Spring Boot Tomcat compatibility, Jakarta EE migration, Spring Boot external container issues.