Spring Boot Default and Custom Error Handling
The default error-handling mechanism in Spring Boot is designed to provide a standard response for unhandled exceptions in web applications, including REST APIs and web-based user interfaces. Here’s an overview of how Spring Boot handles errors by default:
1. Default Error Handling in Spring Boot
When an unhandled exception occurs in a Spring Boot application, the framework uses its default error-handling mechanism, which relies on:
Error Controller:
- The built-in
BasicErrorControllerhandles error responses. - This controller processes errors and returns an appropriate response, either in JSON (for REST APIs) or as an HTML error page (for web applications).
Error Attributes:
- The
DefaultErrorAttributesclass collects error details and makes them available for rendering in the response.
Error Pages:
- By default, Spring Boot serves an HTML error page if the client accepts
text/html. - For REST APIs, a JSON response is returned if the client accepts
application/json.
2. Default JSON Error Response
For REST APIs, the default error response typically includes the following fields:
{
"timestamp": "2024-12-15T12:34:56.789",
"status": 500,
"error": "Internal Server Error",
"message": "NullPointerException",
"path": "/api/resource"
}Fields Explained:
- timestamp: When the error occurred.
- status: HTTP status code (e.g., 404 for Not Found, 500 for Internal Server Error).
- error: A brief error description.
- message: The exception’s message (if available).
- path: The URL path where the error occurred.
3. Customizing Default Error Handling
Spring Boot allows easy customization of its default error-handling behavior. Below are some common methods for customization:
a. Custom Error Messages
You can configure error messages for specific HTTP status codes by adding error pages in src/main/resources/templates/error/.
Example:
- Add an
error.htmlfile for general errors. - Add
error-404.htmlfor 404 errors orerror-500.htmlfor 500 errors.
<!-- src/main/resources/templates/error.html -->
<!DOCTYPE html>
<html>
<head>
<title>Error</title>
</head>
<body>
<h1>Something went wrong!</h1>
</body>
</html>b. Customize Error Attributes
You can extend the DefaultErrorAttributes class to modify the default JSON error response.
Example:
@Component
public class CustomErrorAttributes extends DefaultErrorAttributes {
@Override
public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
Map<String, Object> errorAttributes = super.getErrorAttributes(webRequest, options);
errorAttributes.put("customMessage", "Custom error message");
return errorAttributes;
}
}c. Use @ControllerAdvice for Global Exception Handling
Define a global exception handler using @ControllerAdvice and @ExceptionHandler.
Example:
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(Exception.class)
public ResponseEntity<Map<String, Object>> handleException(Exception ex, WebRequest request) {
Map<String, Object> response = new HashMap<>();
response.put("timestamp", LocalDateTime.now());
response.put("message", ex.getMessage());
response.put("details", request.getDescription(false));
return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
}
}d. Override the Error Controller
You can replace the default BasicErrorController with a custom implementation.
Example:
@RestController
@RequestMapping("/error")
public class CustomErrorController implements ErrorController {
@GetMapping
public ResponseEntity<Map<String, Object>> handleError(HttpServletRequest request) {
Map<String, Object> response = new HashMap<>();
response.put("status", request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE));
response.put("message", "Custom error response");
return new ResponseEntity<>(response, HttpStatus.INTERNAL_SERVER_ERROR);
}
}4. HTTP Status Codes
Spring Boot automatically maps exceptions to appropriate HTTP status codes:
- 404 (Not Found): No matching handler or endpoint.
- 400 (Bad Request): Invalid request data or parameters.
- 500 (Internal Server Error): Unhandled exceptions.
5. Configuration Properties for Error Handling
Spring Boot provides several configuration options in application.properties to control error handling:
PropertyDescriptionserver.error.pathSet the custom path for the error page (default: /error).server.error.include-stacktraceInclude stack trace in error response (never, on_trace_param, always).server.error.include-messageInclude exception message in the response (never, on_param, always).server.error.whitelabel.enabledEnable/disable the default Whitelabel Error Page (true by default).
Example:
server.error.path=/custom-error
server.error.include-stacktrace=never
server.error.include-message=always6. Advanced Exception Handling
For more advanced use cases:
- Use
ResponseEntityExceptionHandlerto handle Spring MVC exceptions likeMethodArgumentNotValidException.
Example:
@ControllerAdvice
public class CustomRestExceptionHandler extends ResponseEntityExceptionHandler {
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex,
HttpHeaders headers,
HttpStatus status,
WebRequest request) {
Map<String, String> errors = new HashMap<>();
ex.getBindingResult().getFieldErrors().forEach(error ->
errors.put(error.getField(), error.getDefaultMessage())
);
return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
}
}Summary
- Spring Boot’s default error-handling mechanism provides structured responses for unhandled exceptions.
- It can be customized at various levels, from modifying error attributes to implementing global exception handlers.
- For REST APIs, the default mechanism outputs helpful JSON responses, while for web applications, HTML error pages are displayed.
