Custom exception classes in Spring Boot

Introduction

Custom exception classes help you handle specific errors in your Spring Boot app clearly. They make your code easier to understand and fix.

When you want to show a clear error message for a specific problem in your app.

When you need to handle different errors differently in your REST API.

When you want to separate system errors from user input errors.

When you want to add extra information to an error for logging or debugging.

When you want to create cleaner and reusable error handling code.

Syntax

Spring Boot

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

Custom exceptions usually extend RuntimeException for unchecked exceptions.

Include constructors to pass error messages or causes.

Examples

This exception can be used when a requested resource is not found.

Spring Boot

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

This exception handles invalid input errors and can include a cause.

Spring Boot

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

    public InvalidInputException(String message, Throwable cause) {
        super(message, cause);
    }
}

Sample Program

This example shows a custom exception UserNotFoundException used in a service. The controller catches it and returns a 404 error with a message.

Spring Boot

package com.example.demo.exception;

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

// Usage in a service class
package com.example.demo.service;

import com.example.demo.exception.UserNotFoundException;
import org.springframework.stereotype.Service;

@Service
public class UserService {
    public String findUserById(int id) {
        if (id != 1) { // pretend only user with id=1 exists
            throw new UserNotFoundException("User with id " + id + " not found.");
        }
        return "User1";
    }
}

// Controller to handle the exception
package com.example.demo.controller;

import com.example.demo.exception.UserNotFoundException;
import com.example.demo.service.UserService;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/users/{id}")
    public String getUser(@PathVariable int id) {
        return userService.findUserById(id);
    }

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

Important Notes

Always create meaningful exception names to describe the error clearly.

Use @ExceptionHandler in controllers to handle custom exceptions and send proper HTTP responses.

Custom exceptions improve code readability and error management in Spring Boot apps.

Summary

Custom exceptions let you handle specific errors clearly in your app.

They extend RuntimeException and include constructors for messages.

Use @ExceptionHandler to catch and respond to these exceptions in controllers.