NUHMAN.com

In Spring Boot applications, a 404 Not Found error typically means the requested URL doesn’t match any controller endpoint, or you're deliberately signaling that a resource wasn't found. This article covers:

• Common causes of 404s in Spring Boot
• How to debug unexpected 404 errors
• Multiple ways to explicitly return 404 responses in REST APIs
• How to use custom exceptions and global exception handling

Use these strategies to build reliable, user-friendly RESTful services.

❗ Common Reasons Spring Boot Returns a 404

🔹 1. Incorrect URL or Path

Ensure that the URL you're accessing matches your controller's path and method.

java

@RestController
@RequestMapping("/api")
public class MyController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

// URL must be: http://localhost:8080/api/hello

🔹 2. Controller Not Scanned

Controllers must be in packages scanned by Spring Boot.

java

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

// OR explicitly define scanning:
@SpringBootApplication
@ComponentScan(basePackages = "com.example.controllers")

🔹 3. Wrong HTTP Method

Check that your controller method matches the request method (e.g., GET vs POST).

java

// If using POST, make sure your client sends POST
@PostMapping("/submit")
public String submitData() {
    return "Submitted!";
}

🔹 4. Missing View in Thymeleaf Apps

If using Thymeleaf, ensure templates exist in src/main/resources/templates.

🔹 5. Custom Error Handling Conflicts

Check for misconfigured @ControllerAdvice that may intercept or redirect requests.

✅ How to Explicitly Return a 404 Response

✅ 1. Using ResponseStatusException

A quick and direct way to throw a 404:

java

@GetMapping("/item/{id}")
public String getItem(@PathVariable String id) {
    boolean exists = false;
    if (!exists) {
        throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Item not found");
    }
    return "Item details";
}

✅ 2. Returning ResponseEntity

java

@GetMapping("/item/{id}")
public ResponseEntity<String> getItem(@PathVariable String id) {
    boolean exists = false;
    if (!exists) {
        return new ResponseEntity<>("Item not found", HttpStatus.NOT_FOUND);
    }
    return new ResponseEntity<>("Item details", HttpStatus.OK);
}

✅ 3. Custom Exception with @ResponseStatus

java

@ResponseStatus(HttpStatus.NOT_FOUND)
public class ItemNotFoundException extends RuntimeException {
    public ItemNotFoundException(String message) {
        super(message);
    }
}

// Controller
@GetMapping("/item/{id}")
public String getItem(@PathVariable String id) {
    throw new ItemNotFoundException("Item not found");
}

✅ 4. Global Exception Handling with @ControllerAdvice

Create a centralized handler for cleaner code:

java

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ItemNotFoundException.class)
    public ResponseEntity<String> handleItemNotFound(ItemNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

🧪 Bonus Tips for Troubleshooting

• ✅ Enable Debug Logging to view endpoint mappings:

yaml

logging:
  level:
    org.springframework.web: DEBUG

• ✅ Check Request URL and Method in Postman or browser
• ✅ Test with curl to confirm endpoint response

📌 Summary Table

StrategyPurposeResponseStatusExceptionQuick way to return 404ResponseEntity with 404 statusFine-grained response controlCustom Exception with @ResponseStatusClean semantic exception mapping@ControllerAdvice global handlerCentralized error handling