{"record":{"id":"ba8bbae16bf6ff7e","repo":"eclipse-vertx/vert.x","slug":"multipart-form-requires-multipart-form-data-conten","errorCode":null,"errorMessage":"Multipart form requires multipart/form-data content type instead of \" + HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED","messagePattern":"Multipart form requires multipart/form-data content type instead of \" \\+ HttpHeaders\\.APPLICATION_X_WWW_FORM_URLENCODED","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientRequestImpl.java","lineNumber":308,"sourceCode":"  }\n\n  @Override\n  public Future<HttpClientResponse> send(ClientForm body) {\n    ClientMultipartFormImpl impl = (ClientMultipartFormImpl) body;\n    String contentType = headers != null ? headers.get(HttpHeaders.CONTENT_TYPE) : null;\n    boolean multipartMixed = impl.mixed();\n    HttpPostRequestEncoder.EncoderMode encoderMode = multipartMixed ? HttpPostRequestEncoder.EncoderMode.RFC1738 : HttpPostRequestEncoder.EncoderMode.HTML5;\n    ClientMultipartFormUpload form;\n    try {\n      boolean multipart;\n      if (contentType == null) {\n        multipart = impl.isMultipart();\n        contentType = multipart ? HttpHeaders.MULTIPART_FORM_DATA.toString() : HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED.toString();\n        putHeader(HttpHeaderNames.CONTENT_TYPE, contentType);\n      } else {\n        if (contentType.equalsIgnoreCase(HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED.toString())) {\n          if (impl.isMultipart()) {\n            throw new IllegalStateException(\"Multipart form requires multipart/form-data content type instead of \"\n              + HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED);\n          }\n          multipart = false;\n        } else if (contentType.equalsIgnoreCase(HttpHeaders.MULTIPART_FORM_DATA.toString())) {\n          multipart = true;\n        } else {\n          throw new IllegalStateException(\"Sending form requires multipart/form-data or \"\n            + HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED + \" content type instead of \" + contentType);\n        }\n      }\n      form = new ClientMultipartFormUpload(context, impl, multipart, encoderMode);\n    } catch (Exception e) {\n      reset(0, e);\n      return response();\n    }\n    for (Map.Entry<String, String> header : form.headers()) {\n      if (header.getKey().equalsIgnoreCase(CONTENT_LENGTH.toString())) {\n        if (Integer.parseInt(header.getValue()) < 0) {","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientRequestImpl.java#L290-L326","documentation":"Vert.x throws this IllegalStateException when you pass a MultiPartForm to HttpClientRequest.send() but the request's Content-Type header is set to application/x-www-form-urlencoded. A multipart form body (with boundaries) is not encoded in the URL-encoded format, so sending it would produce a malformed request body.","triggerScenarios":"Calling send() on a request whose form is a MultiPartForm (e.g. set via HttpClientRequest.setMultipartForm or form upload mode) while the Content-Type header was explicitly set to application/x-www-form-urlencoded, typically via putHeader(\"Content-Type\", ...) or setContentType before send.","commonSituations":"File-upload code that copies a Content-Type header from a plain form example; frameworks or interceptors that force application/x-www-form-urlencoded on all POSTs; migrating code from urlencoded forms to multipart uploads without updating the header.","solutions":["Remove the explicit putHeader/setContentType of application/x-www-form-urlencoded and let Vert.x set multipart/form-data automatically when a multipart form is present","Set the Content-Type to multipart/form-data (or use HttpHeaders.MULTIPART_FORM_DATA) instead of application/x-www-form-urlencoded","Use a plain (non-multipart) Form instead of MultiPartForm if you actually intend to send urlencoded data"],"exampleFix":"// before\nrequest.putHeader(HttpHeaders.CONTENT_TYPE, HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED);\nrequest.setMultipartForm(form);\n// after\nrequest.setMultipartForm(form); // Vert.x sets multipart/form-data automatically","handlingStrategy":"validation","validationCode":"if (form instanceof MultiPartForm && HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED.contentEqualsIgnoreCase(request.headers().get(HttpHeaders.CONTENT_TYPE))) {\n  request.headers().remove(HttpHeaders.CONTENT_TYPE);\n}","typeGuard":"boolean isMultipartCompatible(String contentType) {\n  return contentType == null\n    || HttpHeaders.MULTIPART_FORM_DATA.contentEqualsIgnoreCase(contentType)\n    || HttpHeaders.APPLICATION_X_WWW_FORM_URLENCODED.contentEqualsIgnoreCase(contentType);\n}","tryCatchPattern":null,"preventionTips":["Do not set Content-Type manually when submitting forms; let Vert.x derive it","Centralize form submission in one helper that owns header logic","Audit interceptors that force application/x-www-form-urlencoded on all requests"],"tags":["http","multipart","content-type","client"],"backgroundTag":"invalid-argument-value","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}