Handling not found exceptions in Spring Boot - Step-by-Step Execution

Concept Flow - Handling not found exceptions

Client sends request

↓

Controller receives request

↓

Service searches for resource

↓

Resource found?

No→Throw NotFoundException

↓

Exception Handler catches

↓

Return resource data

↓

Return 404 response

↓

Send response to client

The client requests a resource; if the resource is missing, a NotFoundException is thrown and caught by a handler that returns a 404 response.

Execution Sample

Spring Boot

public ResponseEntity<User> getUser(Long id) {
  User user = userService.findById(id)
    .orElseThrow(() -> new UserNotFoundException(id));
  return ResponseEntity.ok(user);
}

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

This code tries to find a user by ID; if not found, it throws an exception caught by a handler that returns a 404 error.

Execution Table

Step	Action	Resource Found?	Exception Thrown	Response Sent
1	Client requests user with id=5	N/A	No	No
2	Controller calls service to find user	No	No	No
3	Service returns empty Optional	No	No	No
4	orElseThrow triggers UserNotFoundException	No	Yes	No
5	ExceptionHandler catches UserNotFoundException	No	No	No
6	Handler returns 404 Not Found with message	No	No	Yes

💡 Execution stops after sending 404 response because resource was not found.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
user	null	null	null	Exception thrown	Exception handled

Key Moments - 2 Insights

Why does the exception get thrown at step 4?

Because the service returned an empty Optional, orElseThrow triggers the UserNotFoundException as shown in execution_table row 4.

What happens after the exception is thrown?

The exception is caught by the ExceptionHandler method, which sends a 404 response, as shown in rows 5 and 6.

Visual Quiz - 3 Questions

Look at the execution table, at which step is the UserNotFoundException thrown?

A Step 2

B Step 4

C Step 6

D Step 1

💡 Hint

Check the 'Exception Thrown' column in the execution_table at step 4.

According to the variable tracker, what is the value of 'user' after step 3?

A null

B Optional.empty

C User object

D Exception thrown

💡 Hint

Look at the 'user' row in variable_tracker after step 3.

If the user was found at step 3, what would change in the execution table?

A Exception would still be thrown at step 4

B ExceptionHandler would catch an exception anyway

C No exception thrown and 200 OK response sent

D Response would be 404 Not Found

💡 Hint

Refer to the 'Resource Found?' and 'Response Sent' columns in execution_table.

Concept Snapshot

Handling Not Found Exceptions in Spring Boot:
- Use Optional.orElseThrow() to throw a custom exception if resource missing.
- Define @ExceptionHandler method to catch that exception.
- Return ResponseEntity with 404 status and message.
- This cleanly separates normal flow and error handling.
- Client receives clear 404 response when resource not found.

Full Transcript

In Spring Boot, when a client requests a resource, the controller calls the service to find it. If the resource is missing, the service returns an empty Optional. Using orElseThrow, the controller throws a custom NotFoundException. This exception is caught by an @ExceptionHandler method that returns a 404 Not Found response with a message. This flow ensures the client knows the resource was not found. The variable 'user' remains null since the exception is thrown before assignment. The exception handler sends the final response. This pattern cleanly handles missing data scenarios.

Practice

1. What is the main purpose of handling not found exceptions in a Spring Boot application?

easy

A. To improve database performance

B. To log all user activities

C. To automatically retry failed requests

D. To return a clear 404 status when a requested resource is missing

Solution

1. Step 1: Understand the role of not found exceptions

   Not found exceptions indicate that a requested resource does not exist on the server.

2. Step 2: Identify the correct response behavior

   Returning a 404 HTTP status code clearly informs the client that the resource is missing.

3. Final Answer:

   To return a clear 404 status when a requested resource is missing -> Option D

4. Quick Check:

   Not found exceptions = 404 status [OK]

Hint: Not found means resource missing, so send 404 status [OK]

Common Mistakes:

• Confusing not found with server errors
• Thinking it improves database speed
• Assuming it retries requests automatically

2. Which annotation is used in Spring Boot to mark a custom exception class to return HTTP 404 status automatically?

easy

A. @ResponseStatus(HttpStatus.NOT_FOUND)

B. @ExceptionHandler(HttpStatus.NOT_FOUND)

C. @NotFoundException

D. @HttpStatusCode(404)

Solution

1. Step 1: Recall Spring Boot annotations for HTTP status

   The @ResponseStatus annotation sets the HTTP status code for exceptions or controller methods.

2. Step 2: Match the annotation to 404 status

   Using @ResponseStatus(HttpStatus.NOT_FOUND) on a custom exception class sends 404 automatically.

3. Final Answer:

   @ResponseStatus(HttpStatus.NOT_FOUND) -> Option A

4. Quick Check:

   @ResponseStatus + NOT_FOUND = 404 [OK]

Hint: Use @ResponseStatus with NOT_FOUND for 404 exceptions [OK]

Common Mistakes:

• Using @ExceptionHandler instead of @ResponseStatus
• Assuming @NotFoundException is a valid annotation
• Using incorrect annotation names

3. Given this controller method in Spring Boot:

 @GetMapping("/items/{id}")
 public Item getItem(@PathVariable Long id) {
     return itemRepository.findById(id)
         .orElseThrow(() -> new ItemNotFoundException(id));
 }

What happens if the item with the given id does not exist?

medium

A. The method returns null and HTTP 200 status

B. An ItemNotFoundException is thrown and HTTP 404 status is returned

C. The server crashes with a NullPointerException

D. The method returns an empty Item object

Solution

1. Step 1: Analyze the use of orElseThrow

   If the item is not found, orElseThrow triggers the custom ItemNotFoundException.

2. Step 2: Understand exception handling with @ResponseStatus

   If ItemNotFoundException is annotated with @ResponseStatus(HttpStatus.NOT_FOUND), Spring returns 404 status.

3. Final Answer:

   An ItemNotFoundException is thrown and HTTP 404 status is returned -> Option B

4. Quick Check:

   orElseThrow + @ResponseStatus = 404 error [OK]

Hint: orElseThrow triggers exception, annotated exception sends 404 [OK]

Common Mistakes:

• Assuming null is returned instead of exception
• Confusing 404 with 500 server error
• Thinking empty object is returned

4. Consider this code snippet:

 @ResponseStatus(HttpStatus.NOT_FOUND)
 public class ProductNotFoundException extends RuntimeException {
     public ProductNotFoundException(Long id) {
         super("Product " + id + " not found");
     }
 }

 @GetMapping("/products/{id}")
 public Product getProduct(@PathVariable Long id) {
     return productRepo.findById(id).orElseThrow(() -> new ProductNotFoundException(id));
 }

What is the likely problem if the client always receives HTTP 500 instead of 404 when a product is missing?

medium

A. The exception is thrown but Spring does not map it to 404

B. The exception is not annotated with @ResponseStatus

C. The controller method does not handle the exception explicitly

D. The exception class is missing a no-argument constructor

Solution

1. Step 1: Verify annotation presence

   The exception class is correctly annotated with @ResponseStatus(HttpStatus.NOT_FOUND).

2. Step 2: Understand Spring's exception mapping

   If Spring returns 500, it means it does not recognize the exception mapping to 404, possibly due to package scanning or configuration issues.

3. Final Answer:

   The exception is thrown but Spring does not map it to 404 -> Option A

4. Quick Check:

   Annotated exception but 500 means mapping failed [OK]

Hint: 500 instead of 404 means Spring missed exception mapping [OK]

Common Mistakes:

• Assuming missing no-arg constructor causes 500
• Thinking @ResponseStatus is missing when it is present
• Believing explicit handler is always required

5. You want to create a global exception handler in Spring Boot that returns a JSON error with 404 status and a message when any ResourceNotFoundException occurs. Which approach correctly achieves this?

hard

A. Use @RestController on the exception class and return 404 status

B. Annotate ResourceNotFoundException with @ResponseStatus(HttpStatus.NOT_FOUND) only, no handler needed

C. Create a class annotated with @ControllerAdvice and a method with @ExceptionHandler(ResourceNotFoundException.class) returning ResponseEntity with status 404 and error body

D. Throw ResponseStatusException with 404 inside every controller method manually

Solution

1. Step 1: Understand global exception handling

   Using @ControllerAdvice with @ExceptionHandler allows centralized handling of exceptions across controllers.

2. Step 2: Return ResponseEntity with 404 and JSON body

   The handler method can build a ResponseEntity with HttpStatus.NOT_FOUND and a JSON error message for clients.

3. Final Answer:

   Create a class annotated with @ControllerAdvice and a method with @ExceptionHandler(ResourceNotFoundException.class) returning ResponseEntity with status 404 and error body -> Option C

4. Quick Check:

   Global handler + ResponseEntity = custom 404 JSON [OK]

Hint: Use @ControllerAdvice + @ExceptionHandler for global JSON 404 [OK]

Common Mistakes:

• Relying only on @ResponseStatus without custom JSON body
• Annotating exception class as controller
• Manually throwing exceptions in every method