flowable/flowable-engine · error · FlowableException

org.apache.http.entity.mime.MultipartEntityBuilder is not pr

Error message

org.apache.http.entity.mime.MultipartEntityBuilder is not present on the classpath. Multi value parts cannot be used. If you want to use, please make sure that the org.apache.httpcomponents:httpmime dependency is available

What it means

Flowable's Apache HttpClient 4.x based HTTP client supports multi-value multipart request bodies only when the optional `org.apache.httpcomponents:httpmime` artifact is on the classpath. `MultipartEntityBuilder` lives in that optional dependency; when it is absent, `setRequestEntity` refuses to build multipart requests rather than failing later with a NoClassDefFoundError. This is an explicit, early capability check.

Source

Thrown at modules/flowable-http-common/src/main/java/org/flowable/http/common/impl/apache/ApacheHttpComponentsFlowableHttpClient.java:279

                    if (value instanceof byte[]) {
                        if (StringUtils.isNotBlank(part.getMimeType())) {
                            entityBuilder.addBinaryBody(name, (byte[]) value, ContentType.create(part.getMimeType()), part.getFilename());
                        } else {
                            entityBuilder.addBinaryBody(name, (byte[]) value, ContentType.DEFAULT_BINARY, part.getFilename());
                        }
                    } else if (value instanceof String) {
                        if (StringUtils.isNotBlank(part.getMimeType())) {
                            entityBuilder.addTextBody(name, (String) value, ContentType.create(part.getMimeType()));
                        } else {
                            entityBuilder.addTextBody(name, (String) value);
                        }
                    } else if (value != null) {
                        throw new FlowableIllegalArgumentException("Value of type " + value.getClass() + " is not supported as multi part content");
                    }
                }
                requestBase.setEntity(entityBuilder.build());
            } else {
                throw new FlowableException("org.apache.http.entity.mime.MultipartEntityBuilder is not present on the classpath."
                        + " Multi value parts cannot be used."
                        + " If you want to use, please make sure that the org.apache.httpcomponents:httpmime dependency is available");
            }

        } else if (requestInfo.getFormParameters() != null) {
            Map<String, List<String>> formParameters = requestInfo.getFormParameters();
            List<BasicNameValuePair> parameters = new ArrayList<>(formParameters.size());
            for (Map.Entry<String, List<String>> entry : formParameters.entrySet()) {
                String name = entry.getKey();
                for (String value : entry.getValue()) {
                    parameters.add(new BasicNameValuePair(name, value));
                }
            }

            if (StringUtils.isNotEmpty(requestInfo.getBodyEncoding())) {
                requestBase.setEntity(new UrlEncodedFormEntity(parameters, requestInfo.getBodyEncoding()));
            } else {
                requestBase.setEntity(new UrlEncodedFormEntity(parameters));

View on GitHub (pinned to d6d39ce1c6)

Solutions

Add the dependency: Maven `org.apache.httpcomponents:httpmime` (version matching your httpclient 4.x), or Gradle `implementation 'org.apache.httpcomponents:httpmime:4.5.14'`.
If you do not need multipart bodies, stop sending multi value part parameters in the HTTP task/request configuration and use body/form parameters instead.
Verify with `mvn dependency:tree | grep httpmime` (or Gradle equivalent) that httpmime is actually resolved into the runtime classpath, not marked provided/optional.

Example fix

// before (pom.xml) - httpclient without httpmime
<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpclient</artifactId>
  <version>4.5.14</version>
</dependency>

// after - add the optional httpmime dependency
<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpclient</artifactId>
  <version>4.5.14</version>
</dependency>
<dependency>
  <groupId>org.apache.httpcomponents</groupId>
  <artifactId>httpmime</artifactId>
  <version>4.5.14</version>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

boolean multipartSupported;
try {
  Class.forName("org.apache.http.entity.mime.MultipartEntityBuilder");
  multipartSupported = true;
} catch (ClassNotFoundException e) {
  multipartSupported = false;
}
if (requestInfo.getMultiValuePartParameters() != null && !requestInfo.getMultiValuePartParameters().isEmpty() && !multipartSupported) {
  throw new IllegalStateException("Add org.apache.httpcomponents:httpmime to the classpath before using multi value parts");
}

Try / catch

try {
    response = client.call(requestInfo);
} catch (FlowableException e) {
    if (e.getMessage() != null && e.getMessage().contains("MultipartEntityBuilder")) {
        // fall back to form parameters or fail fast with a config hint
    }
}

Prevention

Always ship httpmime alongside httpclient 4.x when the HTTP tasks may use multipart bodies.
Add a startup smoke test or Class.forName check that fails fast on missing multipart support.
Avoid multi value parts unless actually required; prefer form or body parameters.

When it happens

Trigger: Calling `call()`/`prepareRequest()` on an `ApacheHttpComponentsFlowableHttpClient` with a `FlowableHttpRequestInfo` whose `multiValuePartParameters` (multi value parts) is non-empty while `org.apache.http.entity.mime.MultipartEntityBuilder` is not resolvable on the classpath.

Common situations: Using `flowable-http` in a Spring Boot app without adding httpmime; relying on a transitive httpclient dependency that excludes httpmime; upgrading to httpclient 5.x where the artifact coordinates changed (`org.apache.httpcomponents.client5:httpclient5`), leaving the old optional dep out.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/31019809f0429652. Report an issue: GitHub.