Custom exception classes in Spring Boot - Deep Dive

Overview - Custom exception classes

What is it?

Custom exception classes are special error types you create in your Spring Boot application to represent specific problems that can happen. Instead of using general errors, you define your own exceptions with meaningful names and messages. This helps your program handle errors clearly and respond appropriately.

Why it matters

Without custom exceptions, all errors look the same and it becomes hard to know what went wrong or how to fix it. Custom exceptions let you tell exactly what problem happened, making your app easier to debug and maintain. They also help you give users clear messages and handle errors in a controlled way.

Where it fits

Before learning custom exceptions, you should understand basic Java exceptions and error handling with try-catch blocks. After this, you can learn about global exception handling in Spring Boot using @ControllerAdvice and how to return custom error responses to users.

Mental Model

Core Idea

Custom exception classes are named error types you create to clearly represent specific problems in your app, making error handling precise and meaningful.

Think of it like...

Imagine a mail sorting center where every package has a label describing its contents. Custom exceptions are like special labels that tell workers exactly what kind of problem a package has, so they know how to handle it quickly and correctly.

┌───────────────────────────┐
│       Application         │
│  ┌─────────────────────┐  │
│  │ CustomExceptionA     │  │
│  │ CustomExceptionB     │  │
│  └─────────────────────┘  │
│           │               │
│           ▼               │
│  ┌─────────────────────┐  │
│  │ Exception Handler    │  │
│  └─────────────────────┘  │
└───────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Java Exceptions Basics

Concept: Learn what exceptions are in Java and how they signal errors during program execution.

In Java, exceptions are objects that represent problems during running code, like trying to open a missing file. You can catch exceptions using try-catch blocks to prevent your program from crashing. There are checked exceptions (must be handled) and unchecked exceptions (runtime errors).

Result

You can catch and respond to errors instead of your program stopping unexpectedly.

Understanding basic exceptions is essential because custom exceptions build on this concept to make error handling clearer.

2

Foundation

Creating a Simple Custom Exception Class

Concept: How to define your own exception class by extending Java's Exception or RuntimeException.

To create a custom exception, make a new class that extends Exception (checked) or RuntimeException (unchecked). Add constructors to pass error messages. For example: public class ResourceNotFoundException extends RuntimeException { public ResourceNotFoundException(String message) { super(message); } } This class can now be thrown when a resource is missing.

Result

You have a new error type that clearly describes a specific problem.

Knowing how to create custom exceptions lets you represent different error cases with meaningful names.

3

Intermediate

Throwing and Catching Custom Exceptions

🤔Before reading on: Do you think custom exceptions behave differently when thrown compared to standard exceptions? Commit to your answer.

Concept: Learn how to throw your custom exceptions in code and catch them to handle errors.

You throw a custom exception using the throw keyword, just like standard exceptions: if (user == null) { throw new ResourceNotFoundException("User not found"); } You can catch it in a try-catch block: try { // code that may throw } catch (ResourceNotFoundException e) { // handle specific error } This lets you respond differently to different problems.

Result

Your program can detect and handle specific errors clearly.

Understanding that custom exceptions integrate seamlessly with Java's throw-catch mechanism helps you write precise error handling.

4

Intermediate

Using Custom Exceptions in Spring Boot Services

🤔Before reading on: Do you think Spring Boot automatically handles custom exceptions or do you need extra setup? Commit to your answer.

Concept: How to use custom exceptions inside Spring Boot service classes to signal errors.

In Spring Boot, you throw custom exceptions from service methods when something goes wrong: public User getUserById(Long id) { return userRepository.findById(id) .orElseThrow(() -> new ResourceNotFoundException("User not found")); } This signals to the controller or global handler that a specific error occurred.

Result

Your service layer clearly communicates error conditions using custom exceptions.

Knowing how to throw custom exceptions in services helps separate error detection from error handling.

5

Intermediate

Handling Custom Exceptions with @ControllerAdvice

🤔Before reading on: Do you think you must catch custom exceptions in every controller method? Commit to your answer.

Concept: Learn how to globally handle custom exceptions in Spring Boot using @ControllerAdvice and @ExceptionHandler.

Instead of catching exceptions in every controller, create a class annotated with @ControllerAdvice: @ControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(ResourceNotFoundException.class) public ResponseEntity handleNotFound(ResourceNotFoundException ex) { return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage()); } } This catches all ResourceNotFoundException thrown anywhere and returns a proper HTTP response.

Result

Your app returns consistent error responses without repeating code.

Using global exception handlers improves code cleanliness and user experience by centralizing error responses.

6

Advanced

Adding Custom Fields to Exception Classes

🤔Before reading on: Can custom exceptions carry extra data beyond messages? Commit to your answer.

Concept: How to add extra information like error codes or details to your custom exceptions.

You can add fields to your exception class: public class ApiException extends RuntimeException { private int errorCode; public ApiException(String message, int errorCode) { super(message); this.errorCode = errorCode; } public int getErrorCode() { return errorCode; } } This lets handlers access more info to customize responses.

Result

Your exceptions carry richer context for better error handling.

Knowing how to extend exceptions with extra data enables more flexible and informative error reporting.

7

Expert

Best Practices and Pitfalls in Custom Exceptions

🤔Before reading on: Is it better to make all custom exceptions checked or unchecked? Commit to your answer.

Concept: Learn expert tips on when to use checked vs unchecked exceptions, naming conventions, and avoiding common mistakes.

Experts recommend: - Use unchecked exceptions (extend RuntimeException) for most cases in Spring Boot to avoid cluttering code with throws declarations. - Name exceptions clearly, e.g., ResourceNotFoundException. - Avoid catching generic Exception; catch specific exceptions. - Document your exceptions. - Use global handlers for consistent responses. These practices keep code clean and maintainable.

Result

Your error handling is robust, clear, and easy to maintain.

Understanding these best practices prevents common bugs and improves collaboration in real projects.

Under the Hood

Custom exceptions are Java classes that extend the Exception or RuntimeException class. When thrown, the Java runtime creates an exception object and unwinds the call stack until a matching catch block is found. Spring Boot's DispatcherServlet catches exceptions from controllers and passes them to @ControllerAdvice handlers if present. This mechanism allows separating error detection (throwing) from error handling (catching).

Why designed this way?

Java's exception system was designed to separate normal code flow from error handling, making programs easier to read and maintain. Custom exceptions extend this by letting developers define meaningful error types for their domain. Spring Boot builds on this by providing global handling to avoid repetitive try-catch blocks in controllers, improving developer productivity and user experience.

┌───────────────┐
│  Service Code │
│  throws      │
│  CustomExcep │
└──────┬────────┘
       │ throws
       ▼
┌───────────────┐
│ Controller    │
│ (no catch)    │
└──────┬────────┘
       │ exception propagates
       ▼
┌───────────────┐
│ @ControllerAdv│
│  ice Handler  │
│  catches ex   │
└──────┬────────┘
       │ returns
       ▼
┌───────────────┐
│ HTTP Response │
│ with error    │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think all custom exceptions must extend Exception (checked) to be useful? Commit to yes or no.

Common Belief: Custom exceptions should always extend Exception to force handling.

Reality: In Spring Boot, it's better to extend RuntimeException (unchecked) for custom exceptions to avoid cluttering code with throws declarations.

Why it matters: Using checked exceptions unnecessarily makes code verbose and harder to maintain, causing developers to catch or declare exceptions they don't need to.

Quick: Do you think you must catch every custom exception in every controller method? Commit to yes or no.

Common Belief: You must catch custom exceptions in every controller method to handle errors.

Reality: Spring Boot allows global handling of exceptions using @ControllerAdvice, so you don't need to catch them everywhere.

Why it matters: Catching exceptions everywhere leads to repetitive code and inconsistent error responses.

Quick: Do you think custom exceptions automatically return user-friendly messages without extra setup? Commit to yes or no.

Common Belief: Throwing a custom exception automatically shows a nice error message to users.

Reality: You must handle exceptions and map them to HTTP responses with messages; otherwise, users see generic errors.

Why it matters: Without proper handling, users get confusing errors, hurting user experience.

Quick: Do you think adding many fields to custom exceptions is always good? Commit to yes or no.

Common Belief: Adding lots of extra data to exceptions makes them more useful.

Reality: Too much data in exceptions can make them heavy and harder to maintain; keep them focused on essential info.

Why it matters: Overloading exceptions with data can cause confusion and bugs in error handling.

Expert Zone

1

Custom exceptions should be immutable to avoid accidental changes during error handling.

2

Using exception cause chaining (passing original exceptions) preserves error context for debugging.

3

Global exception handlers can differentiate responses based on exception types and fields for fine-grained control.

When NOT to use

Avoid custom exceptions for trivial errors that can be handled with standard exceptions like IllegalArgumentException. For validation errors, consider using Spring's built-in validation framework instead of custom exceptions.

Production Patterns

In production, custom exceptions are used with global handlers to return structured JSON error responses with codes and messages. They integrate with logging frameworks to record error details and with monitoring tools to alert on specific exception types.

Connections

Error Handling in Distributed Systems

Builds-on

Understanding custom exceptions helps grasp how errors propagate and are managed across services in distributed systems.

Domain-Driven Design (DDD)

Builds-on

Custom exceptions often represent domain-specific errors, aligning with DDD principles to model real-world problems clearly.

Human Communication and Signaling

Analogy-based connection

Just like clear signals in communication prevent misunderstandings, custom exceptions provide clear signals in code to prevent error confusion.

Common Pitfalls

#1 Catching generic Exception hides specific errors.

Wrong approach:

try {
// code
} catch (Exception e) {
// generic catch
}

Correct approach:

try {
// code
} catch (ResourceNotFoundException e) {
// handle specific error
}

Root cause:

Beginners catch all exceptions to avoid crashes but lose control over specific error handling.

#2 Throwing checked exceptions everywhere makes code verbose.

Wrong approach:

public void method() throws IOException, SQLException {
// many throws
}

Correct approach:

public void method() {
// throw unchecked exceptions instead
}

Root cause:

Misunderstanding when to use checked vs unchecked exceptions leads to cluttered method signatures.

#3 Not using @ControllerAdvice leads to repetitive error handling code.

Wrong approach:

@GetMapping
public ResponseEntity getUser() {
try {
// code
} catch (ResourceNotFoundException e) {
return ResponseEntity.status(404).body(null);
}
}

Correct approach:

@ControllerAdvice
public class GlobalHandler {
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity handle() {
return ResponseEntity.status(404).body("User not found");
}
}

Root cause:

Not knowing global handlers leads to duplicated try-catch blocks.

Key Takeaways

Custom exception classes let you represent specific problems clearly in your Spring Boot app.

They integrate with Java's throw-catch system and Spring Boot's global handlers for clean error management.

Using unchecked exceptions is preferred in Spring Boot to keep code simple and readable.

Global exception handling with @ControllerAdvice centralizes error responses and improves user experience.

Adding meaningful names and optional extra data to exceptions helps maintain and debug your application.

Practice

1. What is the main purpose of creating a custom exception class in Spring Boot?

easy

A. To automatically fix errors without any code changes

B. To replace all built-in exceptions with your own versions

C. To make the application run faster by skipping error checks

D. To handle specific error cases clearly and separately in your application

Solution

1. Step 1: Understand the role of custom exceptions

   Custom exceptions help you identify and manage specific error situations clearly in your code.

2. Step 2: Compare with other options

   Replacing all exceptions or auto-fixing errors is not the goal; custom exceptions improve clarity and control.

3. Final Answer:

   To handle specific error cases clearly and separately in your application -> Option D

4. Quick Check:

   Custom exceptions clarify error handling = C [OK]

Hint: Custom exceptions clarify specific errors clearly [OK]

Common Mistakes:

• Thinking custom exceptions replace all errors
• Believing they fix errors automatically
• Assuming they improve performance directly

2. Which of the following is the correct way to declare a custom exception class in Spring Boot?

easy

A. public class MyException extends RuntimeException { public MyException(String message) { super(message); } }

B. public interface MyException extends RuntimeException {}

C. public class MyException implements RuntimeException {}

D. public class MyException extends Exception {}

Solution

1. Step 1: Check correct inheritance

   Custom exceptions usually extend RuntimeException to avoid mandatory try-catch blocks.

2. Step 2: Verify constructor usage

   Providing a constructor that calls super(message) is standard to pass error messages.

3. Final Answer:

   public class MyException extends RuntimeException { public MyException(String message) { super(message); } } -> Option A

4. Quick Check:

   Extend RuntimeException with constructor = D [OK]

Hint: Extend RuntimeException and add constructor with message [OK]

Common Mistakes:

• Using implements instead of extends
• Extending Exception instead of RuntimeException
• Declaring interface instead of class

3. Given this custom exception class:

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

What will happen if this exception is thrown in a Spring Boot controller without any handler?

medium

A. The exception will be ignored and the request will succeed

B. The application will return a 500 Internal Server Error response

C. The application will automatically return a 404 Not Found response

D. The server will crash and stop running

Solution

1. Step 1: Understand default Spring Boot behavior

   Without a handler, Spring Boot treats RuntimeExceptions as server errors and returns HTTP 500.

2. Step 2: Check other options

   Ignoring exceptions or auto 404 responses require explicit handling; server crash does not happen.

3. Final Answer:

   The application will return a 500 Internal Server Error response -> Option B

4. Quick Check:

   Unhandled RuntimeException = HTTP 500 error [OK]

Hint: Unhandled RuntimeException returns HTTP 500 by default [OK]

Common Mistakes:

• Assuming automatic 404 response
• Thinking exceptions are ignored
• Believing server crashes on exception

4. Identify the error in this custom exception class:

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

medium

A. The class should extend Exception, not RuntimeException

B. The first constructor should accept a message parameter

C. The second method should be a constructor but is declared as void

D. There is no error; the class is correct

Solution

1. Step 1: Check method declarations

   The second method has a return type void, so it is not a constructor but a normal method.

2. Step 2: Understand constructor syntax

   Constructors must not have a return type; this causes the message constructor to be invalid.

3. Final Answer:

   The second method should be a constructor but is declared as void -> Option C

4. Quick Check:

   Constructor must not have return type = B [OK]

Hint: Constructors have no return type, not even void [OK]

Common Mistakes:

• Adding void to constructor
• Confusing methods with constructors
• Extending wrong exception class

5. How can you handle a custom exception ResourceMissingException globally in Spring Boot to return a 404 status with a custom message?

hard

A. Create a @ControllerAdvice class with a method annotated @ExceptionHandler(ResourceMissingException.class) that returns ResponseEntity with status 404 and message

B. Throw ResourceMissingException inside a try-catch block and catch it in every controller method separately

C. Override the default error page in Spring Boot without using @ExceptionHandler

D. Use @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR) on the exception class

Solution

1. Step 1: Use @ControllerAdvice for global handling

   This annotation allows centralized exception handling across all controllers.

2. Step 2: Define @ExceptionHandler method for ResourceMissingException

   This method can build a ResponseEntity with HTTP 404 and a custom message to send back.

3. Final Answer:

   Create a @ControllerAdvice class with a method annotated @ExceptionHandler(ResourceMissingException.class) that returns ResponseEntity with status 404 and message -> Option A

4. Quick Check:

   Global handler with @ExceptionHandler = A [OK]

Hint: Use @ControllerAdvice and @ExceptionHandler for global exception handling [OK]

Common Mistakes:

• Catching exceptions in every controller method
• Using wrong HTTP status annotation
• Overriding error page without exception handler