Skip to content
javahacks.dev
Spring MVC

Fix HttpMediaTypeNotSupportedException in a Spring MVC App

Fix the 415 Unsupported Media Type error by sending the right Content-Type header, matching the consumes attribute and checking the message converters.

6 min read
Summarize in AI
Flat illustration of a log with a failing line and a wrench, with the Spring, Spring Boot and Apache Maven logos.

The server log shows it clearly:

Text
org.springframework.web.HttpMediaTypeNotSupportedException: Content-Type 'text/plain;charset=UTF-8' is not supported

and the client sees 415. Spring MVC picks a message converter by the request's Content-Type. If none of the registered converters can read that type into the parameter, it gives up. The path from filter to handler is in how Spring MVC handles a request.

Cause 1: the client did not send the header

Shell
curl -i -X POST localhost:8080/api/orders -d '{"customerId":"c1"}'

curl -d sends application/x-www-form-urlencoded by default, even though the data looks like JSON. Add the header:

Shell
curl -i -X POST localhost:8080/api/orders \
  -H 'Content-Type: application/json' \
  -d '{"customerId":"c1"}'

In JavaScript, fetch with a string body defaults to text/plain; set headers: { 'Content-Type': 'application/json' } and JSON.stringify the body. In Postman or similar tools, choose "raw" with the JSON type, which sets the header for you.

Cause 2: the mapping restricts what it consumes

java
@PostMapping(path = "/orders", consumes = MediaType.APPLICATION_JSON_VALUE)
OrderView create(@RequestBody CreateOrder order) { ... }

With consumes set, a request with any other content type is rejected with 415 before the method runs. This is correct when an endpoint accepts JSON only. If you also accept XML or form data, list the types or remove the attribute. Check the class-level @RequestMapping as well; it applies to every method.

Cause 3: sending a form to a JSON endpoint

A browser form posts application/x-www-form-urlencoded. A handler with @RequestBody expects a converter for that type into an object, and the default converters do not provide one. Use @ModelAttribute (or no annotation) for form data:

java
@PostMapping("/signup")
String signup(SignupForm form) { ... }

and keep @RequestBody for JSON.

Cause 4: no converter is available

Spring Boot registers a JSON converter when Jackson is on the classpath, which spring-boot-starter-web (or the equivalent web starter in your version) ensures. A project that excludes Jackson or has a broken dependency set has no way to read JSON, and the error appears for application/json too. Check the classpath with ./mvnw dependency:tree | grep -i jackson. Spring Boot 4 uses Jackson 3 by default, with compatibility modules available for Jackson 2; mixing the two on one classpath can leave one without a registered converter.

Cause 5: multipart without the right mapping

File uploads need multipart/form-data and a handler that takes @RequestParam("file") MultipartFile file or @RequestPart. Posting multipart to a @RequestBody JSON handler produces this error, and so does sending JSON to a handler that expects parts.

Return a helpful response

The default 415 body tells a client very little. Spring adds an Accept header listing what it supports; make sure your advice does not strip it:

java
@ExceptionHandler(HttpMediaTypeNotSupportedException.class)
ResponseEntity<ProblemDetail> unsupported(HttpMediaTypeNotSupportedException e) {
    ProblemDetail p = ProblemDetail.forStatusAndDetail(HttpStatus.UNSUPPORTED_MEDIA_TYPE,
            "Send the body as application/json.");
    return ResponseEntity.status(HttpStatus.UNSUPPORTED_MEDIA_TYPE)
            .headers(e.getHeaders()).body(p);
}

Send the request the endpoint expects

A client that sets the wrong type is the cause more often than the server. A curl call shows the difference in a few seconds:

Shell
# fails with 415: no Content-Type, curl defaults to form encoding for -d
curl -i -X POST localhost:8080/orders -d '{"item":"A"}'

# works
curl -i -X POST localhost:8080/orders -H 'Content-Type: application/json' -d '{"item":"A"}'

With -d, curl sends application/x-www-form-urlencoded unless told otherwise, and a controller with @RequestBody on a JSON object has no converter for it. In Java, the RestClient sets the header when the body is an object and a JSON converter is present, and sets nothing useful for a raw string:

java
restClient.post().uri("/orders")
        .contentType(MediaType.APPLICATION_JSON)
        .body("{\"item\":\"A\"}")
        .retrieve().toBodilessEntity();

State the content type explicitly for string bodies.

The three similar failures

The status codes look alike, and each points to a different side of the exchange:

StatusExceptionThe mismatch is between
415HttpMediaTypeNotSupportedExceptionThe request's Content-Type and what the endpoint consumes
406HttpMediaTypeNotAcceptableExceptionThe request's Accept and what the endpoint produces
400HttpMessageNotReadableExceptionThe body and the parameter type, after the type was accepted

A client that sends valid JSON with Content-Type: text/plain gets a 415. The same client with the right type and a typo in a field gets a 400. A client that asks for Accept: application/xml of a JSON-only endpoint gets a 406. Reading the status first narrows the search by half.

Check what the endpoint declares

An explicit consumes limits an endpoint to the types listed, and an inherited class-level setting can narrow a method by accident:

java
@RestController
@RequestMapping(value = "/orders", consumes = MediaType.APPLICATION_JSON_VALUE)
class OrderController {

    @PostMapping(consumes = {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})
    Order create(@RequestBody Order order) { return order; }
}

The method-level consumes overrides the class-level one. Print the registered mappings with the actuator mappings endpoint, which lists the consumes conditions for each handler, and compare with the header the client sends.

Forms and files need different annotations

A browser form posts application/x-www-form-urlencoded, which binds to a model object or @RequestParam values, not @RequestBody. A file upload posts multipart/form-data and binds with @RequestPart or a MultipartFile parameter:

java
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
String upload(@RequestPart("file") MultipartFile file, @RequestPart("meta") OrderMeta meta) {
    return file.getOriginalFilename();
}

The meta part is JSON inside a multipart request, and the part itself needs its own content type, application/json, or the converter fails with a 415 that names application/octet-stream. Many clients leave that part untyped, so set it in the client.

Pin it down with a test

java
@Test
void rejectsPlainText() throws Exception {
    mvc.perform(post("/orders")
                    .contentType(MediaType.TEXT_PLAIN)
                    .content("item=A"))
       .andExpect(status().isUnsupportedMediaType());
}

@Test
void acceptsJson() throws Exception {
    mvc.perform(post("/orders")
                    .contentType(MediaType.APPLICATION_JSON)
                    .content("{\"item\":\"A\"}"))
       .andExpect(status().isCreated());
}

The pair states the contract, and it keeps working when a library upgrade changes the converters that are registered. Also add the types you do not support to the list of negative cases, since a silent acceptance of the wrong type is the greater risk.

Make the failure self-explanatory

The default body for a 415 says little. A handler can list what the endpoint accepts, which saves the client developer a round trip to the documentation:

java
@ExceptionHandler(HttpMediaTypeNotSupportedException.class)
ProblemDetail unsupported(HttpMediaTypeNotSupportedException e) {
    ProblemDetail p = ProblemDetail.forStatus(HttpStatus.UNSUPPORTED_MEDIA_TYPE);
    p.setDetail("Supported types: " + e.getSupportedMediaTypes());
    return p;
}

The detail names the types in the response, such as [application/json, application/*+json], and the client can fix the header without guessing. Include the same list in the API documentation, and a mismatch becomes rare. Log the received Content-Type at debug level on the server too, since a proxy that rewrites the header produces this error for a client that sent the right one.

Where this does not apply

If the status is 406 Not Acceptable, the problem is the Accept header on the response side, not Content-Type. If the body is read but fails, see [HttpMessageNotReadableException](/library/httpmessagenotreadableexception-fix-json-parse-error). The [@RequestMapping reference](https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-requestmapping.html) explains consumes and produces. A body that arrives with the right type and still fails is [HttpMessageNotReadableException](/library/httpmessagenotreadableexception-fix-json-parse-error), and a 415 caused by the browser is often a CORS preflight in disguise. The Spring MVC reference documents the behavior in detail.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.