Spring Boot: Cannot access REST Controller on localhost (404)

A 404 error occurs when a client (like a browser or Postman) makes a request to a URL that the server cannot match to any defined endpoint in the application.

In Spring Boot, this often happens when:

• The endpoint URL is incorrect.
• The controller is not scanned by Spring Boot.
• The application is not running properly or on a different port.
• The HTTP method (GET, POST, PUT, DELETE) doesn’t match the controller mapping.

Common Causes of 404 Error in Spring Boot

1. Endpoint URL or HTTP Method Mismatch

Ensure the URL you are accessing matches the one defined in the controller. Also, verify the correct HTTP method (@GetMapping, @PostMapping, etc.) is being used.

2. Missing or Incorrect Controller Annotation

The controller must be annotated with either @RestController or @Controller. Without it, Spring Boot won’t detect and register it as a REST endpoint.

3. Application Configuration Issue

Check that the application is running successfully and no other application is using the same port.
If a custom port is configured, ensure you are accessing the correct one in your URL (e.g., localhost:9090 if server.port=9090).

4. Path Variable or Request Parameter Mismatch

If your endpoint includes a path variable (e.g., /api/{id}), ensure you pass it correctly in the request URL.

5. Typographical Errors

A simple spelling mistake in the mapping or URL can cause the 404 error. Double-check both the mapping annotation and the requested URL.

6. CORS (Cross-Origin Resource Sharing) Issues

When accessing endpoints from a different domain (like a frontend app), ensure CORS is configured using @CrossOrigin. Otherwise, requests might be blocked.

Troubleshooting Steps

To identify and fix the 404 issue, follow these steps:

• Check Endpoint Definitions: Verify that the controller class and endpoint mappings are correctly defined.
• Verify Application Status: Ensure the Spring Boot application is running successfully on the intended port.
• Examine Logs: Review the startup logs to confirm that your controller beans are being created.
• Test with Tools: Use Postman, Curl, or a browser to test API endpoints manually.
• Check Configuration: Confirm your project structure follows standard Spring Boot conventions, and your controller is inside a package scanned by @SpringBootApplication.

Step-by-Step Implementation Example

Step 1: Create a Spring Boot Project

Go to Spring Initializr and generate a new project with the following details:

Project: Maven
Language: Java
Spring Boot Version: 3.x (Latest LTS)
Dependencies:

• Spring Web
• Spring Boot DevTools
• Lombok

Once the project is generated, extract and open it in your IDE (IntelliJ IDEA, Eclipse, or STS).

Step 2: Create a REST Controller

Create a new controller class inside the base package (the same package as your main application class).

package com.app;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ParentController {

    @GetMapping("/api/example")
    public String displayData() {
        return "Welcome to GeeksForGeeks";
    }
}

• @RestController marks the class as a RESTful controller.
• @GetMapping("/api/example") maps HTTP GET requests to /api/example.
• The displayData() method returns a simple string response.

Step 3: Run the Application

Run the Spring Boot project using your IDE or command line:

mvn spring-boot:run

By default, Spring Boot runs the embedded Tomcat server on port 8080.

You will see the following message in the console once the server starts successfully:

Step 4: Test the Endpoint

Open your browser or Postman and access the following URL:

http://localhost:8080/api/example

Expected Output:

If you see this message, the controller is working correctly.

Step 5: Example of a 404 Error

Now try hitting an incorrect endpoint, for example:

http://localhost:8080/api/msg

Output:

You will see a Whitelabel Error Page in your browser indicating:

This confirms that the URL you entered does not match any defined endpoint in the application.