The HttpMediaTypeNotAcceptableException in Spring MVC

1. Overview

In this quick article, we’ll have a look at the HttpMediaTypeNotAcceptableException exception, and understand the cases where we might encounter it.

2. The Problem

When implementing an API endpoint with Spring, we generally need to specify the consumed/produced media types (via the consumes and produces parameters). This narrows down the possible formats that the API will return back to the client for that specific operation.

HTTP also has the dedicated “Accept” header – which is used to specify media types the client recognizes and can accept. Simply put, the server will send back a resource representation using one of the media types the client requested.

However, if there is no common type that both sides can work with, Spring will throw the HttpMediaTypeNotAcceptableException exception.

3. Practical Example

Let’s create a simple example that will demonstrate this scenario.

We’re going to use a POST endpoint – which can only work with “application/json“ and returns JSON data back as well:

@PostMapping(
  value = "/test", 
  consumes = MediaType.APPLICATION_JSON_VALUE, 
  produces = MediaType.APPLICATION_JSON_VALUE)
public Map<String, String> example() {
    return Collections.singletonMap("key", "value");
}

Then, let’s send a request using CURL with a non-recognized content type:

curl -X POST --header "Accept: application/pdf" http://localhost:8080/test -v

> POST /test HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.51.0
> Accept: application/pdf

The response we got is:

< HTTP/1.1 406 
< Content-Length: 0

4. The Solution

There’s only one way to resolve the issue – to send/receive one of the supported types.

All we can do is to provide a more descriptive message (by default Spring returns an empty body) with a custom ExceptionHandler notifying a client about all acceptable media types.

In our case, it’s only “application/json”:

@ResponseBody
@ExceptionHandler(HttpMediaTypeNotAcceptableException.class)
public String handleHttpMediaTypeNotAcceptableException() {
    return "acceptable MIME type:" + MediaType.APPLICATION_JSON_VALUE;
}

5. Conclusion

In this tutorial, we’ve considered the HttpMediaTypeNotAcceptableException exception thrown by Spring MVC when there’s a mismatch between what the client asks for and what the server can actually produce.

As always, the code snippets mentioned in the article can be found in our GitHub repository.