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.

The server log shows it clearly:
org.springframework.web.HttpMediaTypeNotSupportedException: Content-Type 'text/plain;charset=UTF-8' is not supportedand 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
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:
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
@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:
@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:
@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:
# 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:
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:
| Status | Exception | The mismatch is between |
|---|---|---|
| 415 | HttpMediaTypeNotSupportedException | The request's Content-Type and what the endpoint consumes |
| 406 | HttpMediaTypeNotAcceptableException | The request's Accept and what the endpoint produces |
| 400 | HttpMessageNotReadableException | The 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:
@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:
@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
@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:
@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.


