flowable/flowable-engine · error · FlowableIllegalArgumentException

Multipart request with file content is required

Error message

Multipart request with file content is required

What it means

After confirming the request is multipart, the endpoint requires at least one file part because the deployment to import is the uploaded file. It reads `multipartRequest.getFileMap()` and throws when the map is empty, meaning the request had form fields but no file content.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/repository/DeploymentCollectionResource.java:182

            @ApiParam(name = "deploymentName") @RequestParam(value = "deploymentName", required = false) String deploymentName,
            @ApiParam(name = "tenantId") @RequestParam(value = "tenantId", required = false) String tenantId,
            HttpServletRequest request) {

        if (!(request instanceof MultipartHttpServletRequest)) {
            throw new FlowableIllegalArgumentException("Multipart request is required");
        }
        
        if (restApiInterceptor != null) {
            restApiInterceptor.executeNewDeploymentForTenantId(tenantId);
        }

        String queryString = request.getQueryString();
        Map<String, String> decodedQueryStrings = splitQueryString(queryString);

        MultipartHttpServletRequest multipartRequest = (MultipartHttpServletRequest) request;

        if (multipartRequest.getFileMap().size() == 0) {
            throw new FlowableIllegalArgumentException("Multipart request with file content is required");
        }

        MultipartFile file = multipartRequest.getFileMap().values().iterator().next();

        try {
            CmmnDeploymentBuilder deploymentBuilder = repositoryService.createDeployment();
            String fileName = file.getOriginalFilename();
            if (StringUtils.isEmpty(fileName) || !(fileName.endsWith(".cmmn.xml") || fileName
                    .endsWith(".cmmn") || fileName.toLowerCase().endsWith(".bar") || fileName
                    .toLowerCase().endsWith(".zip"))) {

                fileName = file.getName();
            }

            if (fileName.endsWith(".cmmn.xml") || fileName.endsWith(".cmmn")) {
                try (final InputStream fileInputStream = file.getInputStream()) {
                    deploymentBuilder.addInputStream(fileName, fileInputStream);
                }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Include the deployment artifact as a file part, e.g. `curl -F 'file=@case.cmmn.xml' .../repository/deployments`.
2. Verify the part is sent as a file (Content-Disposition with filename) so it appears in getFileMap().
3. Check the client library: use the file-upload API (e.g. requests' files=, axios FormData) rather than form body fields.

Example fix

// before (no file part)
form.append('deploymentName', 'myCase');
axios.post('/repository/deployments', form);

// after (file part present)
form.append('file', new File([bytes], 'case.cmmn.xml'));
axios.post('/repository/deployments', form);

if (!form.has('file') || !(form.get('file') instanceof File)) {
  throw new Error('Multipart request must include a file part');
}

When it happens

Trigger: POST a multipart/form-data request to the deployments endpoint where all parts are regular form fields (no file parts), e.g. sending only deploymentKey/deploymentName fields, or the client sent data as form fields instead of a file part.

Common situations: Clients appending deploymentName as a file-less form field while forgetting the file part; scripting tools that turn the payload into text fields; multipart parser configured to treat files as plain parameters.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Multipart request is required
• File must be of type .cmmn.xml, .cmmn, .bar or .zip
• Variable name in the body should be equal to the name used i
• Could not find a case instance with id '${caseInstanceId}'.
• Historic task instance '' variable value for couldn't be fo

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