Configure Spring Boot to Redirect 404 to a Single Page Application

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

In distributed systems, managing multi-step processes (e.g., validating a driver, calculating fares, notifying users) can be difficult. We need to manage state, scattered retry logic, and maintain context when services fail.

Dapr Workflows solves this via Durable Execution which includes automatic state persistence, replaying workflows after failures and built-in resilience through retries, timeouts and error handling.

In this tutorial, we'll see how to orchestrate a multi-step flow for a ride-hailing application by integrating Dapr Workflows and Spring Boot:

>> Dapr Workflows With PubSub

1. Introduction

Single-page applications (SPAs) such as those built with React, Angular, or Vue often rely on client-side routing. When served from a Spring Boot backend, refreshing the page or accessing a wrong link sends a request for a non-existent server path. Spring Boot then returns a 404 error.

To make the SPA work correctly, we need to forward all unmatched requests to index.html with HTTP status 200. This lets the frontend router handle the path.

In this tutorial, we’ll learn how to configure Spring Boot so that all unknown routes are redirected to the SPA’s index.html.

2. Maven Dependency

Let’s start by importing the spring-boot-starter-web dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>

3. Setting Up a Basic SPA with Spring Boot

Let’s consider an SPA deployed with Spring Boot, where the compiled frontend files are placed inside the resources directory:

src/main/resources/static

For example, a minimal index.html could look like:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Baeldung</title>
</head>
<body>
    <h1>Home Page</h1>
</body>
</html>

Next, we create a simple controller to forward the root path:

@Controller
public class HomeController {
    @RequestMapping("/")
    public String getHome(){
        return "forward:/index.html";
    }
}

When a user accesses the root path http://localhost:8080/, Spring Boot serves index.html correctly.

However, if the user refreshes a client-side route like http://localhost:8080/dashboard, Spring Boot tries to find a server mapping for /dashboard and returns 404 Not Found. Instead, we want Spring Boot to return index.html so the SPA router can handle the route.

4. Redirecting 404 Not Found Errors

In this section, we describe some solutions for redirecting unmatched requests to index.html.

4.1. Using a Controller to Forward Unknown Routes

Let’s create a controller that forwards all unmapped paths to index.html:

@Controller
public class SpaForwardController {
    @RequestMapping(value = "/{path:[^\\.]*}")
    public String redirect() {
        return "forward:/";
    }
}

The unmatched requests without a file extension are forwarded to “/”, which returns index.html.

If a specific mapping exists (for example, @GetMapping(“/dashboard”)), Spring selects it with higher precedence, and the catch-all pattern is ignored. For any other path without a matching handler (such as /settings), the request falls through to the catch-all mapping and gets forwarded to index.html.

Also, we need to support deeper routes like /dashboard/settings. To do this, we can expand the controller mapping:

@Controller
public class SpaForwardController {
    @RequestMapping(value = {
        "/{path:[^\\.]*}",
        "/{path:[^\\.]*}/**/{subpath:[^\\.]*}"
    })
    public String redirect() {
        return "forward:/";
    }
}

4.2. Using a Custom Error Controller

Another approach is to intercept 404 errors and redirect them to the SPA entry point:

@Controller
public class SpaErrorController implements ErrorController {
    @RequestMapping("/error")
    public String handleError() {
        return "forward:/index.html";
    }
}

This method ensures that any unknown route eventually loads the SPA.

However, this approach may also intercept real backend 404 errors, which may not always be desirable.

4.3. Using WebMvcConfigurer

Another approach is to centralize error handling and avoid the need to explicitly match route patterns.

We can achieve this by implementing the WebMvcConfigurer interface and registering a custom error page:

@Configuration
public class WebApplicationConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/notFound")
          .setViewName("forward:/index.html");
    }

    @Bean
    public WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> containerCustomizer() {
        return container -> {
            container.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/notFound"));
        };
    }
}

In this configuration, any request that results in a 404 Not Found error is redirected to /notFound. This endpoint then forwards the request to index.html.

However, it also means that all 404 errors—including those from backend APIs—are redirected to the SPA, which may not always be desirable.

5. Test

After starting the Spring Boot application, we can verify the configuration by accessing different URLs.

First, we request the root path:

$ curl -i http://localhost:8080/

The response returns 200 along with the contents of index.html:

HTTP/1.1 200

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Baeldung</title>
</head>
<body>
    <h1>Home Page</h1>
</body>
</html>

Next, we simulate accessing a client-side route:

$ curl -i http://localhost:8080/dashboard

Instead of returning a 404 Not Found, the application responds with 200 and serves index.html. This confirms that the request is forwarded and handled by the SPA router.

6. Conclusion

In this article, we explored how to forward unknown routes to index.html when serving a single-page application with Spring Boot. We examined multiple approaches, including using a custom controller, configuring WebMvcConfigurer, and handling errors via a custom error mapping.

As always, the source code is available over on GitHub.