hs-web/hsweb-framework · warning · UnsupportedMediaTypeStatusException

unsupported_media_type

unsupported_media_type

Error message

error.unsupported_media_type

What it means

In the WebMvc (servlet) advice, NotAcceptableStatusException is mapped to HTTP 406 with code not_acceptable_media_type and the localized 'error.not_acceptable_media_type' message; the supported media types are attached via result(e.getSupportedMediaTypes()). Same semantics as the WebFlux case: the client's Accept header cannot be satisfied.

Solutions

1. Set Accept to a supported type (typically application/json) as listed in the 406 response result.
2. Use Accept: */* to accept whatever the server produces.
3. Add the needed HttpMessageConverter (e.g. MappingJackson2XmlHttpMessageConverter) if non-JSON output is required.
4. Review content-negotiation configuration after framework upgrades that removed path-extension negotiation.

Example fix

// before
requests.get(url, headers={'Accept': 'application/xml'})
// after
requests.get(url, headers={'Accept': 'application/json'})

const accept = 'application/json';
if (!['application/json', '*/*'].includes(accept)) {
  console.warn(`Accept ${accept} unsupported by this Spring MVC endpoint`);
}

try {
  return restTemplate.exchange(url, GET, entity, ResponseMessage.class);
} catch (HttpStatusCodeException e) {
  if (e.getStatusCode() == HttpStatus.NOT_ACCEPTABLE) {
    // retry with Accept: */* or read supportedMediaTypes from the body
  }
  throw e;
}

When it happens

Trigger: Sending an Accept header (e.g. application/xml, vendor types) that none of the registered HttpMessageConverters can produce for the endpoint's return type in a Spring MVC deployment.

Common situations: Clients expecting XML output when only Jackson JSON is on the classpath; overly specific Accept patterns; content negotiation config (favorPathExtension/suffix) changes after a Spring upgrade.

Related errors

• not_acceptable_media_type
• dataSourceService not ready
• unsupported_media_type
• method_not_allowed
• e.getMessage()

AI-assisted analysis of hs-web/hsweb-framework@b2cfc85a57 (2026-09-13). Data as JSON: /api/errors/56c81ad67638ce1d. Report an issue: GitHub.

Appendix: source

Thrown at hsweb-commons/hsweb-commons-crud/src/main/java/org/hswebframework/web/crud/web/CommonWebMvcErrorControllerAdvice.java:206

        log.warn(e.getLocalizedMessage(), e);

        return ResponseMessage.error(400, e.getCode(), resolveMessage(e));
    }

    @ExceptionHandler
    @ResponseStatus(HttpStatus.UNSUPPORTED_MEDIA_TYPE)
    public ResponseMessage<Object> handleException(UnsupportedMediaTypeStatusException e) {
        log.warn(e.getLocalizedMessage(), e);

        return ResponseMessage
            .error(415, "unsupported_media_type", LocaleUtils.resolveMessage("error.unsupported_media_type"))
            .result(e.getSupportedMediaTypes());
    }

    @ExceptionHandler
    @ResponseStatus(HttpStatus.NOT_ACCEPTABLE)
    public ResponseMessage<Object> handleException(NotAcceptableStatusException e) {
        log.warn(e.getLocalizedMessage(), e);

        return ResponseMessage
            .error(406, "not_acceptable_media_type", LocaleUtils
                .resolveMessage("error.not_acceptable_media_type"))
            .result(e.getSupportedMediaTypes());
    }

    @ExceptionHandler
    @ResponseStatus(HttpStatus.NOT_ACCEPTABLE)
    public ResponseMessage<Object> handleException(MethodNotAllowedException e) {
        log.warn(e.getLocalizedMessage(), e);

        return ResponseMessage
            .error(406, "method_not_allowed", LocaleUtils.resolveMessage("error.method_not_allowed"))
            .result(e.getSupportedMethods());
    }

View on GitHub (pinned to b2cfc85a57)