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

java

spring-boot

rest-controller

error-handling

byAnton Shumikhin·Dec 25, 2024

Ensure your `@RestController`'s `@RequestMapping` path matches your HTTP request. The `@SpringBootApplication` should be above your controller's package hierarchy. Here's a quick example:

// Application.java in the base-level package
@SpringBootApplication
public class Application { /* Move along, nothing to see here. */ }

// Controller.java in a sub-level package
@RestController
@RequestMapping("/api")
public class Controller {
    @GetMapping("/example") // Check the path: /api/example
    public String getExample() {
        return "It's Working, It's Working! - Anakin Skywalker";
    }
}

The endpoint will be: **http://localhost:<port>/api/example**. The port, HTTP request type and `spring-boot-starter-web` dependency must align.

Are your components scanned correctly?

If facing a 404 error, ensure your @RestController is present in a package scanned by Spring Boot. Spring Boot automatically scans packages under the one with your @SpringBootApplication main class. You can use @ComponentScan explicitly for out-of-place controllers:

@ComponentScan(basePackageClasses = YourController.class)

Or for multiple controllers in different packages:

@ComponentScan(basePackages = {"com.example.book", "com.example.author"})

Keep your @SpringBootApplication class in the root package, ensuring all your controllers in sub-packages will be scanned.

Double check your URL mappings

URL mappings on your @RestController's methods are defined via @RequestMapping or @GetMapping annotations. The complete URL is composed of the server context path + controller's request mapping + method's request mapping.

@RestController
@RequestMapping("/api")
public class YourController {
    @GetMapping("/book") // Full path: /api/book
    public ResponseEntity<?> getBook() { /* All the world's a page. */ }
}

Ensure the URL in the client's HTTP request matches the complete URL path you've defined.

Have you tried turning it off and on again?

Errors like 404 might indicate Spring Boot isn't starting on the correct port:

Verify application starts without any "I've made a huge mistake" moments.
Check console logs for the listening port ("Ah, Port 8080, we meet again").
Ensure there are no port conflicts or surprise port changes in application.properties.

Do you need a map of your application context?

Spring Boot auto-configures components saving you configuration headaches, but it's useful to inspect bean definitions when issues arise:

Use your debugger to inspect the Spring application context's bean registrations.
Use actuator endpoints like /beans or /mappings for a runtime health-check.
Examine your application's auto-configuration report generated at startup. It's like spring's diary.

Some more nifty tips

spring-boot-starter-web better be in your Maven or Gradle build file.
Review your @RestController for any case of Annotation Amnesia – missing @RequestMapping or @GetMapping annotations.
If cross-origin issues arise, add @CrossOrigin if calling from a different domain.
Debug with breakpoints in your controller. It's like tossing a fishing line for bugs.
For Spring Security users, scan your security configurations – they might block access.