HttpMediaTypeNotSupportedException in Spring Boot

Spring Boot applications leverage the Spring Web module to create robust and scalable web applications. However, when working with web requests, it's possible to encounter certain exceptions. One such exception is the HttpMediaTypeNotSupportedException.

What is HttpMediaTypeNotSupportedException?

HttpMediaTypeNotSupportedException is thrown when the client sends a request with a media type that is not supported by the application. This can happen, for instance, if your controller endpoint is expecting a request with content type application/json, but the client sends a request with content type text/xml.

Here is the Exception Trace:

org.springframework.web.HttpMediaTypeNotSupportedException: Content type 'text/xml' not supported
    at org.springframework.web.servlet.mvc.method.annotation.AbstractMessageConverterMethodArgumentResolver.readWithMessageConverters(AbstractMessageConverterMethodArgumentResolver.java:239)
    at org.springframework.web.servlet.mvc.method.annotation.RequestResponseBodyMethodProcessor.readWithMessageConverters(RequestResponseBodyMethodProcessor.java:157)
    at org.springframework.web.servlet.mvc.method.annotation.RequestResponseBodyMethodProcessor.resolveArgument(RequestResponseBodyMethodProcessor.java:130)
    at org.springframework.web.method.support.HandlerMethodArgumentResolverComposite.resolveArgument(HandlerMethodArgumentResolverComposite.java:127)
    ... more

How to reproduce?

Let's consider a simple Spring Boot controller:

@RestController
@RequestMapping("/api/greetings")
public class GreetingController {

    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<String> greet(@RequestBody String name) {
        return ResponseEntity.ok("Hello, " + name);
    }
}

Call REST API:

Now, if you send a POST request to /api/greetings with the header Content-Type: text/plain, you'll encounter the exception.

Exception in the console:

Solutions

Specify Supported Media Types

Make it clear in your controller which media types are supported using the consumes attribute:

@PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)

Handle the Exception

Use Spring's @ExceptionHandler to catch the exception and provide a meaningful response:

@ExceptionHandler(HttpMediaTypeNotSupportedException.class)
public ResponseEntity<String> handleTypeNotSupported(HttpMediaTypeNotSupportedException e) {
    return ResponseEntity.badRequest().body("Content type not supported.");
}

Client Awareness

Ensure clients are aware of the expected content type. This often means updating API documentation or providing clear error messages for developers.

Use Spring's ContentNegotiationConfigurer

You can further customize how media types are resolved using this in a configuration class.

Conclusion

Handling media types correctly is crucial in a web application to ensure seamless client-server interactions. The HttpMediaTypeNotSupportedException gives developers a clear signal that there's a mismatch, and handling it gracefully can make the development process smoother.