Spring Boot Global Exception Handling: The Complete Guide

package io.thecodeforge.exception;

import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.UUID;

/**
 * io.thecodeforge: Single source of truth for all API error responses.
 *
 * Design decisions explained:
 *   - LinkedHashMap preserves insertion order in the JSON response — fields appear
 *     in a predictable sequence that the frontend team can depend on
 *   - Instant instead of LocalDateTime for timestamp — Instant is UTC and unambiguous
 *     in multi-timezone environments; LocalDateTime is server-local and misleading
 *   - traceId in every response — a UUID that appears in both the response and the
 *     server logs, enabling support teams to find the exact stack trace for any incident
 *   - HttpServletRequest parameter — extracts the actual request path without
 *     hardcoding it, works for any endpoint without modification
 */
@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    // ── Business Exceptions ──────────────────────────────────────────────────

    @ExceptionHandler(ForgeResourceNotFoundException.class)
    public ResponseEntity<Map<String, Object>> handleResourceNotFound(
            ForgeResourceNotFoundException ex,
            HttpServletRequest request) {

        // 4xx: WARN level — not a system failure, a client error
        log.warn("Resource not found [path={}]: {}", request.getRequestURI(), ex.getMessage());

        return buildErrorResponse(
            HttpStatus.NOT_FOUND,
            "Resource Not Found",
            ex.getMessage(),
            "ERR_RES_404",
            request.getRequestURI()
        );
    }

    @ExceptionHandler(ForgeBusinessRuleException.class)
    public ResponseEntity<Map<String, Object>> handleBusinessRuleViolation(
            ForgeBusinessRuleException ex,
            HttpServletRequest request) {

        // Business rule violations are expected failure paths — WARN, not ERROR
        log.warn("Business rule violation [path={}, code={}]: {}",
            request.getRequestURI(), ex.getErrorCode(), ex.getMessage());

        return buildErrorResponse(
            HttpStatus.UNPROCESSABLE_ENTITY,
            "Business Rule Violation",
            ex.getMessage(),
            ex.getErrorCode(),
            request.getRequestURI()
        );
    }

    // ── Catch-All Safety Net ─────────────────────────────────────────────────

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handleGeneralException(
            Exception ex,
            HttpServletRequest request) {

        // 5xx: ERROR level with full stack trace — this is a system failure
        // The traceId links this log line to the response the client received
        String traceId = UUID.randomUUID().toString();
        log.error("Unhandled exception [traceId={}, path={}]",
            traceId, request.getRequestURI(), ex);

        // Return a sanitized response — no class names, no stack frames, no library versions
        Map<String, Object> body = new LinkedHashMap<>();
        body.put("timestamp", Instant.now().toString());
        body.put("status", HttpStatus.INTERNAL_SERVER_ERROR.value());
        body.put("error", "Internal Server Error");
        body.put("message",
            "An unexpected error occurred. Contact support with reference: " + traceId);
        body.put("traceId", traceId);
        body.put("path", request.getRequestURI());

        return new ResponseEntity<>(body, HttpStatus.INTERNAL_SERVER_ERROR);
    }

    // ── Shared Builder ───────────────────────────────────────────────────────

    private ResponseEntity<Map<String, Object>> buildErrorResponse(
            HttpStatus status,
            String error,
            String message,
            String errorCode,
            String path) {

        Map<String, Object> body = new LinkedHashMap<>();
        body.put("timestamp", Instant.now().toString());
        body.put("status", status.value());
        body.put("error", error);
        body.put("message", message);
        body.put("errorCode", errorCode);
        body.put("path", path);

        return new ResponseEntity<>(body, status);
    }
}

package io.thecodeforge.exception;

/**
 * io.thecodeforge: Base exception for all application-specific exceptions.
 *
 * Design: extends RuntimeException so exceptions propagate through the call
 * chain without requiring checked exception declarations on every method.
 * The errorCode field provides a machine-readable identifier for the frontend
 * and support teams — distinct from the human-readable message.
 */
public abstract class ForgeException extends RuntimeException {

    private final String errorCode;

    protected ForgeException(String message, String errorCode) {
        super(message);
        this.errorCode = errorCode;
    }

    protected ForgeException(String message, String errorCode, Throwable cause) {
        super(message, cause);
        this.errorCode = errorCode;
    }

    public String getErrorCode() {
        return errorCode;
    }
}

// ── Domain-specific exceptions ───────────────────────────────────────────────

// ForgeResourceNotFoundException.java
package io.thecodeforge.exception;

public class ForgeResourceNotFoundException extends ForgeException {

    public ForgeResourceNotFoundException(String resourceType, Object resourceId) {
        super(
            String.format("%s with ID '%s' was not found", resourceType, resourceId),
            "ERR_RES_404"
        );
    }
}

// ForgeBusinessRuleException.java
package io.thecodeforge.exception;

public class ForgeBusinessRuleException extends ForgeException {

    public ForgeBusinessRuleException(String message, String errorCode) {
        super(message, errorCode);
    }
}

// ForgeConflictException.java
package io.thecodeforge.exception;

public class ForgeConflictException extends ForgeException {

    public ForgeConflictException(String message, String errorCode) {
        super(message, errorCode);
    }
}

// Usage in service layer — no try-catch, exceptions propagate naturally:
// public Product getProduct(Long id) {
//     return productRepository.findById(id)
//         .orElseThrow(() -> new ForgeResourceNotFoundException("Product", id));
// }
//
// public void processPayment(PaymentRequest request) {
//     if (isDuplicate(request)) {
//         throw new ForgeBusinessRuleException(
//             "A payment for this order has already been processed",
//             "PAYMENT_DUPLICATE"
//         );
//     }
// }

// Add this handler to GlobalExceptionHandler — do not create a separate @RestControllerAdvice
// Having two @RestControllerAdvice classes for these two concerns introduces ordering ambiguity

import org.springframework.validation.FieldError;
import org.springframework.validation.ObjectError;
import org.springframework.web.bind.MethodArgumentNotValidException;

// Inside GlobalExceptionHandler class:

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, Object>> handleValidationException(
        MethodArgumentNotValidException ex,
        HttpServletRequest request) {

    // Field-level errors: @NotNull, @Email, @Size on individual fields
    Map<String, String> fieldErrors = new LinkedHashMap<>();
    for (FieldError error : ex.getBindingResult().getFieldErrors()) {
        // putIfAbsent: keep the first error per field if multiple constraints fail simultaneously
        fieldErrors.putIfAbsent(error.getField(), error.getDefaultMessage());
    }

    // Class-level errors: @PasswordMatches, @DateRangeValid on the whole object
    // These are often missed — they appear in getGlobalErrors(), not getFieldErrors()
    List<String> globalErrors = ex.getBindingResult().getGlobalErrors()
        .stream()
        .map(ObjectError::getDefaultMessage)
        .collect(Collectors.toList());

    // 4xx: WARN level — client sent invalid input, not a system failure
    log.warn("Validation failed [path={}, fieldErrors={}, globalErrors={}]",
        request.getRequestURI(), fieldErrors.size(), globalErrors.size());

    Map<String, Object> body = new LinkedHashMap<>();
    body.put("timestamp", Instant.now().toString());
    body.put("status", HttpStatus.BAD_REQUEST.value());
    body.put("error", "Validation Failed");
    body.put("message", "Request contains " + fieldErrors.size() + " validation error(s)");
    body.put("fieldErrors", fieldErrors);
    if (!globalErrors.isEmpty()) {
        body.put("globalErrors", globalErrors);
    }
    body.put("path", request.getRequestURI());

    return new ResponseEntity<>(body, HttpStatus.BAD_REQUEST);
}

// Controller — @Valid is the trigger, without it this handler is never invoked:
@PostMapping("/users")
public ResponseEntity<UserDto> createUser(@Valid @RequestBody UserDto dto) {
    // Spring validates dto before this method body executes
    // If validation fails, MethodArgumentNotValidException is thrown here
    // GlobalExceptionHandler intercepts it before the method body runs
    return ResponseEntity.status(HttpStatus.CREATED).body(userService.create(dto));
}

// DTO with mixed field and class-level constraints:
@PasswordMatches  // class-level constraint — goes to globalErrors
public class UserRegistrationDto {

    @NotBlank(message = "Email is required")
    @Email(message = "Please provide a valid email address")
    private String email;

    @NotBlank(message = "Password is required")
    @Size(min = 8, message = "Password must be at least 8 characters")
    private String password;

    @NotBlank(message = "Password confirmation is required")
    private String confirmPassword;
}

// Additional handlers to add to GlobalExceptionHandler
// for coverage of HTTP-level exceptions

import org.springframework.web.HttpRequestMethodNotSupportedException;
import org.springframework.web.servlet.NoHandlerFoundException;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.security.core.AuthenticationException;

// ── HTTP-level exceptions (inside GlobalExceptionHandler class) ──────────────

// Handles: GET /api/v1/users/999 where 999 does not exist in the URL pattern
// Requires: spring.mvc.throw-exception-if-no-handler-found=true
//           spring.web.resources.add-mappings=false
// in application.properties
@ExceptionHandler(NoHandlerFoundException.class)
public ResponseEntity<Map<String, Object>> handleNoHandlerFound(
        NoHandlerFoundException ex,
        HttpServletRequest request) {

    log.warn("No handler found [method={}, path={}]",
        ex.getHttpMethod(), request.getRequestURI());

    return buildErrorResponse(
        HttpStatus.NOT_FOUND,
        "Endpoint Not Found",
        String.format("No endpoint found for %s %s",
            ex.getHttpMethod(), request.getRequestURI()),
        "ERR_ENDPOINT_404",
        request.getRequestURI()
    );
}

// Handles: POST to an endpoint that only supports GET
@ExceptionHandler(HttpRequestMethodNotSupportedException.class)
public ResponseEntity<Map<String, Object>> handleMethodNotSupported(
        HttpRequestMethodNotSupportedException ex,
        HttpServletRequest request) {

    log.warn("Method not supported [method={}, path={}, supported={}]",
        ex.getMethod(), request.getRequestURI(), ex.getSupportedMethods());

    return buildErrorResponse(
        HttpStatus.METHOD_NOT_ALLOWED,
        "Method Not Allowed",
        String.format("Method '%s' is not supported for this endpoint. Supported: %s",
            ex.getMethod(),
            String.join(", ", ex.getSupportedHttpMethods()
                .stream().map(Object::toString).collect(Collectors.toList()))),
        "ERR_METHOD_405",
        request.getRequestURI()
    );
}

// Handles: Spring Security AccessDeniedException (authenticated user lacks permission)
// Note: For Spring Security, you may also need to configure ExceptionTranslationFilter
@ExceptionHandler(AccessDeniedException.class)
public ResponseEntity<Map<String, Object>> handleAccessDenied(
        AccessDeniedException ex,
        HttpServletRequest request) {

    // Deliberate: do not log the user's identity or the specific permission that was checked
    // That information should not appear in application logs for compliance reasons
    log.warn("Access denied [path={}]", request.getRequestURI());

    return buildErrorResponse(
        HttpStatus.FORBIDDEN,
        "Access Denied",
        "You do not have permission to perform this action",
        "ERR_ACCESS_403",
        request.getRequestURI()
    );
}

package io.thecodeforge.exception;

import io.thecodeforge.controller.ProductController;
import io.thecodeforge.service.ProductService;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.hamcrest.Matchers.*;
import static org.mockito.ArgumentMatchers.anyLong;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

/**
 * io.thecodeforge: Exception handler tests using @WebMvcTest.
 *
 * @WebMvcTest loads only the web layer — faster than @SpringBootTest.
 * MockMvc simulates HTTP requests without starting the actual server.
 * Tests verify HTTP status, JSON structure, and specific field values.
 */
@WebMvcTest(controllers = ProductController.class)
class GlobalExceptionHandlerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private ProductService productService;

    @Test
    void shouldReturn404WithStructuredResponse_whenProductNotFound() throws Exception {
        // Arrange: service throws the exception that should produce 404
        when(productService.getProduct(anyLong()))
            .thenThrow(new ForgeResourceNotFoundException("Product", 9999L));

        // Act + Assert: verify status, content type, and every JSON field
        mockMvc.perform(get("/api/v1/products/9999")
                .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isNotFound())
            .andExpect(content().contentType(MediaType.APPLICATION_JSON))
            .andExpect(jsonPath("$.status").value(404))
            .andExpect(jsonPath("$.error").value("Resource Not Found"))
            .andExpect(jsonPath("$.errorCode").value("ERR_RES_404"))
            .andExpect(jsonPath("$.message").value(containsString("9999")))
            .andExpect(jsonPath("$.timestamp").exists())
            .andExpect(jsonPath("$.path").value("/api/v1/products/9999"))
            // Verify stack trace is NOT in the response — security requirement
            .andExpect(jsonPath("$.trace").doesNotExist())
            .andExpect(jsonPath("$.exception").doesNotExist());
    }

    @Test
    void shouldReturn400WithFieldErrors_whenDtoValidationFails() throws Exception {
        String invalidBody = "{\"email\": \"not-an-email\", \"password\": \"abc\"}";

        mockMvc.perform(post("/api/v1/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(invalidBody))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.status").value(400))
            .andExpect(jsonPath("$.error").value("Validation Failed"))
            .andExpect(jsonPath("$.fieldErrors.email").exists())
            .andExpect(jsonPath("$.fieldErrors.password").exists())
            // Verify both fields have error messages, not null
            .andExpect(jsonPath("$.fieldErrors.email").isString())
            .andExpect(jsonPath("$.fieldErrors.password").isString());
    }

    @Test
    void shouldReturn500WithTraceId_whenUnexpectedExceptionOccurs() throws Exception {
        // Simulate an unexpected runtime error in the service
        when(productService.getProduct(anyLong()))
            .thenThrow(new RuntimeException("Database connection pool exhausted"));

        mockMvc.perform(get("/api/v1/products/1")
                .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isInternalServerError())
            .andExpect(jsonPath("$.status").value(500))
            // traceId must be present — support team needs it
            .andExpect(jsonPath("$.traceId").exists())
            .andExpect(jsonPath("$.traceId").isString())
            // Internal exception message must NOT be in the response — security requirement
            .andExpect(jsonPath("$.message")
                .value(not(containsString("Database connection pool exhausted"))))
            .andExpect(jsonPath("$.message")
                .value(containsString("Contact support with reference")));
    }

    @Test
    void shouldReturn200_whenProductExists() throws Exception {
        // Verify the happy path still works — exception handling should not affect it
        when(productService.getProduct(1L))
            .thenReturn(new ProductDto(1L, "Forge Drill", 149.50));

        mockMvc.perform(get("/api/v1/products/1")
                .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.id").value(1));
    }
}