{"record":{"id":"99d8ff7e36a480b4","repo":"eclipse-vertx/vert.x","slug":"request-must-have-a-valid-content-type-header-to-d","errorCode":null,"errorMessage":"Request must have a valid content-type header to decode a multipart request","messagePattern":"Request must have a valid content-type header to decode a multipart request","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/HttpServerRequestImpl.java","lineNumber":418,"sourceCode":"\n  @Override\n  public Future<NetSocket> toNetSocket() {\n    return response.netSocket(this);\n  }\n\n  @Override\n  public HttpServerRequest setExpectMultipart(boolean expect) {\n    synchronized (connection) {\n      checkEnded();\n      expectMultipart = expect;\n      if (expect) {\n        if (postRequestDecoder == null) {\n          String contentType = headersMap.get(HttpHeaderNames.CONTENT_TYPE);\n          if (contentType == null) {\n            throw new IllegalStateException(\"Request must have a content-type header to decode a multipart request\");\n          }\n          if (!HttpUtils.isValidMultipartContentType(contentType)) {\n            throw new IllegalStateException(\"Request must have a valid content-type header to decode a multipart request\");\n          }\n          if (!HttpUtils.isValidMultipartMethod(method.toNetty())) {\n            throw new IllegalStateException(\"Request method must be one of POST, PUT, PATCH or DELETE to decode a multipart request\");\n          }\n          HttpRequest req = new DefaultHttpRequest(\n            io.netty.handler.codec.http.HttpVersion.HTTP_1_1,\n            method.toNetty(),\n            uri);\n          req.headers().add(HttpHeaderNames.CONTENT_TYPE, contentType);\n          NettyFileUploadDataFactory factory = new NettyFileUploadDataFactory(context, this, () -> uploadHandler);\n          factory.setMaxLimit(maxFormAttributeSize);\n          postRequestDecoder = new HttpPostRequestDecoder(factory, req, HttpConstants.DEFAULT_CHARSET, maxFormFields, maxFormBufferedBytes);\n        }\n      } else {\n        postRequestDecoder = null;\n      }\n    }\n    return this;","sourceCodeStart":400,"sourceCodeEnd":436,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/HttpServerRequestImpl.java#L400-L436","documentation":"setExpectMultipart(true) validates the Content-Type header via HttpUtils.isValidMultipartContentType before creating the Netty multipart decoder. If the header exists but is not multipart/form-data (or a valid multipart variant), an IllegalStateException is thrown because the body cannot be decoded as multipart.","triggerScenarios":"Calling request.setExpectMultipart(true) when the Content-Type is present but not multipart, e.g. application/json, application/x-www-form-urlencoded, text/plain.","commonSituations":"Enabling multipart unconditionally for all POST routes including JSON APIs; clients mislabeling the content type; forgetting the boundary parameter in the content type.","solutions":["Send the request with Content-Type: multipart/form-data; boundary=<boundary>","Only call setExpectMultipart(true) when the request's Content-Type indicates multipart","Inspect request.getHeader(\"Content-Type\") and route to a JSON/form decoder instead when it isn't multipart"],"exampleFix":"// before\nrequest.setExpectMultipart(true); // throws for application/json\n\n// after\nString ct = request.getHeader(\"Content-Type\");\nif (ct != null && ct.toLowerCase().startsWith(\"multipart/form-data\")) {\n  request.setExpectMultipart(true);\n} else {\n  // handle other body types\n}","handlingStrategy":"validation","validationCode":"String ct = request.getHeader(HttpHeaders.CONTENT_TYPE);\nif (ct == null || !ct.toLowerCase().startsWith(\"multipart/form-data\")) {\n  request.response().setStatusCode(415).end();\n  return;\n}\nrequest.setExpectMultipart(true);","typeGuard":null,"tryCatchPattern":"try {\n  request.setExpectMultipart(true);\n} catch (IllegalStateException e) {\n  // content type not multipart; use another decoder\n}","preventionTips":["Only enable multipart for multipart/form-data requests","Dispatch decoders based on Content-Type","Ensure clients include the boundary parameter"],"tags":["http","multipart","content-type","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}