Handling not found exceptions in Spring Boot

Introduction

Handling not found exceptions helps your app respond clearly when something is missing. It avoids crashes and tells users what went wrong.

When a user requests a resource that does not exist, like a missing product or user.

When searching a database and no matching record is found.

When an API call expects an item but it is not available.

When validating input that refers to something that should exist but doesn't.

Syntax

Spring Boot

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;

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

Use @ResponseStatus(HttpStatus.NOT_FOUND) to set the HTTP status code to 404.

Extend RuntimeException to create a custom unchecked exception.

Examples

A simple custom exception without HTTP status annotation.

Spring Boot

public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(String message) {
        super(message);
    }
}

This exception returns 404 status automatically when thrown.

Spring Boot

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

Global handler to catch and respond to not found exceptions with a message.

Spring Boot

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ResourceNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

Sample Program

This Spring Boot app has a simple user map. When you ask for a user by ID, it returns the name if found. If not, it throws UserNotFoundException. The exception handler sends a 404 status with a clear message.

Spring Boot

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

@SpringBootApplication
@RestController
public class DemoApplication {

    private Map<Integer, String> users = new ConcurrentHashMap<>();

    public DemoApplication() {
        users.put(1, "Alice");
        users.put(2, "Bob");
    }

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

    @GetMapping("/users/{id}")
    public String getUser(@PathVariable int id) {
        String user = users.get(id);
        if (user == null) {
            throw new UserNotFoundException("User with id " + id + " not found.");
        }
        return user;
    }

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

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<String> handleUserNotFound(UserNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

Important Notes

Always provide a clear message in your exception to help users and developers understand the problem.

Use @ControllerAdvice for global exception handling across all controllers.

Returning proper HTTP status codes improves API usability and debugging.

Summary

Custom exceptions help handle missing resources cleanly.

Use @ResponseStatus(HttpStatus.NOT_FOUND) or exception handlers to send 404 status.

Clear error messages improve user experience and debugging.