eclipse-vertx/vert.x · error

415 Unsupported Media Type

Error message

415 Unsupported Media Type

What it means

SC_UNSUPPORTED_MEDIA_TYPE is the HttpResponseExpectation constant for HTTP 415 Unsupported Media Type. Vert.x provides it for response validation; a 415 failing this expectation surfaces '415 Unsupported Media Type'. The server refuses the request because the Content-Type (or the media type of the submitted resource) is not one it can process for that endpoint.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java:225

  /**
   * 412 Precondition Failed
   */
  HttpResponseExpectation SC_PRECONDITION_FAILED = status(412);

  /**
   * 413 Request Entity Too Large
   */
  HttpResponseExpectation SC_REQUEST_ENTITY_TOO_LARGE = status(413);

  /**
   * 414 Request-URI Too Long
   */
  HttpResponseExpectation SC_REQUEST_URI_TOO_LONG = status(414);

  /**
   * 415 Unsupported Media Type
   */
  HttpResponseExpectation SC_UNSUPPORTED_MEDIA_TYPE = status(415);

  /**
   * 416 Requested Range Not Satisfiable
   */
  HttpResponseExpectation SC_REQUESTED_RANGE_NOT_SATISFIABLE = status(416);

  /**
   * 417 Expectation Failed
   */
  HttpResponseExpectation SC_EXPECTATION_FAILED = status(417);

  /**
   * 421 Misdirected Request
   */
  HttpResponseExpectation SC_MISDIRECTED_REQUEST = status(421);

  /**
   * 422 Unprocessable Entity (WebDAV, RFC4918)

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Set the correct Content-Type header explicitly: putHeader("Content-Type", "application/json")
2. Prefer typed helpers: webClient.post(...).sendJson(obj) or sendBuffer with .putHeader — avoid bare sendBuffer for structured bodies
3. Check the endpoint documentation (or an OPTIONS request) for accepted media types
4. For multipart uploads, set the part's MIME type (e.g. application/octet-stream for binary)
5. Verify you did not accidentally send a serialized string of JSON with Content-Type text/plain

Example fix

// before
webClient.post(url).sendBuffer(jsonBuffer); // 415
// after
webClient.post(url)
  .putHeader("Content-Type", "application/json")
  .sendBuffer(jsonBuffer);
// or simply: .sendJson(jsonObject)

// Always declare the body media type
if (bodyMediaType == null || bodyMediaType.isBlank()) {
  bodyMediaType = "application/json"; // or detect per payload
}
request.putHeader("Content-Type", bodyMediaType);

boolean isUnsupportedMediaType(Throwable t) {
  return t instanceof VertxHttpResponseException
    && ((VertxHttpResponseException) t).getResponse().statusCode() == 415;
}

if (isUnsupportedMediaType(t)) { resendWithExplicitContentType(); } else { throw t; }

When it happens

Trigger: Sending a request body via Vert.x WebClient with a Content-Type the endpoint rejects — e.g. sending JSON as text/plain, forgetting putHeader("Content-Type", "application/json"), sending XML to a JSON-only API, or uploading with a wrong/missing MIME type in multipart.

Common situations: Using sendBuffer (which sets no Content-Type) instead of sendJson, typos in the media type string, API version change adding/removing supported formats, file uploads with mismatched extension/MIME.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Multipart form requires multipart/form-data content type ins
• Sending form requires multipart/form-data or " + HttpHeaders
• Request must have a content-type header to decode a multipar
• Request must have a valid content-type header to decode a mu
• Request must have a valid content-type header to decode a mu

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/929612daca9ba183. Report an issue: GitHub.