Introduction

A JSP page returning 404 in Spring Boot usually points to view resolution or packaging configuration, not to controller business logic. JSP support is more sensitive than modern template engines, especially when running as an executable archive. A consistent troubleshooting sequence can identify the failure layer quickly.

Core Sections

Verify Dependencies and Packaging Mode First

JSP rendering needs Jasper and JSTL support. If these dependencies are missing, view names resolve in code but rendering fails at runtime.

For Maven:

1<dependencies>
2  <dependency>
3    <groupId>org.springframework.boot</groupId>
4    <artifactId>spring-boot-starter-web</artifactId>
5  </dependency>
6  <dependency>
7    <groupId>org.apache.tomcat.embed</groupId>
8    <artifactId>tomcat-embed-jasper</artifactId>
9  </dependency>
10  <dependency>
11    <groupId>javax.servlet</groupId>
12    <artifactId>jstl</artifactId>
13  </dependency>
14</dependencies>

If JSP is central to the app, many teams use war packaging for fewer surprises. Jar mode can still work, but compatibility varies by stack and setup details.

<packaging>war</packaging>

Always test the packaged artifact, not only IDE launches, because classpath behavior can differ. Also keep your local Java version aligned with CI and production runtime so resolver behavior does not change unexpectedly between environments.

Put JSP Files in the Expected Location

A common working layout is:

src/main/webapp/WEB-INF/jsp/home.jsp
src/main/webapp/WEB-INF/jsp/dashboard.jsp

Then configure view resolver properties:

spring.mvc.view.prefix=/WEB-INF/jsp/
spring.mvc.view.suffix=.jsp

Controller methods return logical names, not physical paths:

1@Controller
2public class HomeController {
3
4    @GetMapping("/")
5    public String home() {
6        return "home";
7    }
8
9    @GetMapping("/dashboard")
10    public String dashboard() {
11        return "dashboard";
12    }
13}

If prefix or suffix is off by one path segment, Spring returns 404 even though controller mappings are correct.

Check Route and Security Interactions

JSP path issues can be hidden by route collisions or security configuration. A catch all mapping or restrictive rule can make valid JSP pages appear missing.

Run mapping and security checks:

./mvnw spring-boot:run
curl -I http://localhost:8080/
curl -I http://localhost:8080/dashboard

If you use Spring Security, verify route permissions for JSP endpoints. Unauthorized routes may be redirected or masked by custom error handlers.

Example security rule allowing JSP routes:

1@Bean
2SecurityFilterChain security(HttpSecurity http) throws Exception {
3    http
4      .authorizeHttpRequests(auth -> auth
5          .requestMatchers("/", "/dashboard", "/css/**", "/js/**").permitAll()
6          .anyRequest().authenticated())
7      .formLogin();
8    return http.build();
9}

This keeps view routes reachable while preserving authentication for protected endpoints.

Debug View Resolution and Artifact Contents

Enable resolver debug logging to see exactly which JSP path Spring attempts:

logging.level.org.springframework.web.servlet.view=DEBUG

Inspect the packaged output as part of troubleshooting:

./mvnw clean package
jar tf target/app.war | rg 'WEB-INF/jsp|home.jsp|dashboard.jsp'

If JSP files are missing from the artifact, build configuration or source layout is wrong. If files are present but unresolved, resolver prefix or route mapping is likely wrong.

For local smoke tests:

java -jar target/app.war
curl -I http://localhost:8080/

Using a repeatable command set avoids guesswork and quickly narrows the issue.

When to Consider Moving Away From JSP

If the project is new and does not rely on legacy JSP tags, consider Thymeleaf or server side APIs plus a separate frontend. JSP can still work, but operational simplicity is often better with newer stacks. For legacy systems, keeping JSP is fine when dependency, path, and packaging conventions are documented and tested.

Common Pitfalls

• Missing tomcat-embed-jasper or JSTL dependencies.
• JSP files stored outside src/main/webapp/WEB-INF/jsp.
• Incorrect view prefix or suffix values.
• Testing only IDE runtime instead of packaged artifact behavior.
• Route or security rules intercepting JSP endpoints.

Summary

• Start with dependencies, packaging mode, and artifact verification.
• Keep JSP files under WEB-INF/jsp with explicit resolver properties.
• Return logical view names from controllers.
• Validate route and security behavior with direct endpoint checks.
• Use debug logs and archive inspection to locate resolution failures quickly.