flowable/flowable-engine · error · FlowableIllegalArgumentException

Attachment name is required.

Error message

Attachment name is required.

What it means

createSimpleAttachment (JSON path of task attachment creation) requires the AttachmentRequest to carry a name. If attachmentRequest.getName() is null, Flowable throws FlowableIllegalArgumentException("Attachment name is required.") because taskService.createAttachment needs a non-null attachment name.

Solutions

1. Always include a non-null "name" in the attachment JSON body.
2. In client code, default the name from the file name or URL when not provided.
3. Validate required fields (name) before calling the API.
4. If name genuinely is optional for your use case, use the binary attachment endpoint which takes the name from multipart parameters.

Example fix

// before
{"description":"Design doc"}

// after
{"name":"design-doc.pdf","description":"Design doc"}

if (typeof attachment.name !== 'string' || attachment.name.trim() === '') {
  throw new Error('Attachment name is required before calling the API');
}

function hasName(a) { return a != null && typeof a.name === 'string' && a.name.length > 0; }

try {
  await api.post(`/tasks/${taskId}/attachments`, attachment);
} catch (e) {
  if (/Attachment name is required/.test(e.response?.data?.message || '')) {
    attachment.name = fallbackName; // e.g. derived from externalUrl
  }
}

When it happens

Trigger: POST /runtime/tasks/{taskId}/attachments with a JSON body that omits the "name" field or sets it to null, e.g. {"description":"only desc"}.

Common situations: Clients assuming only externalUrl or description is needed, optional-field serializers dropping null/empty name keys, API clients built from outdated docs.

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

• A request body was expected when executing the form submit.
• AttachmentRequest properties not found in request
• Error converting request body to RestVariable instance
• Failed to serialize to a AttachmentRequest instance
• Id cannot be null.

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

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/task/TaskAttachmentCollectionResource.java:129

            } catch (Exception e) {
                throw new FlowableIllegalArgumentException("Failed to serialize to a AttachmentRequest instance", e);
            }

            if (attachmentRequest == null) {
                throw new FlowableIllegalArgumentException("AttachmentRequest properties not found in request");
            }

            result = createSimpleAttachment(attachmentRequest, task);
        }

        return result;
    }

    protected AttachmentResponse createSimpleAttachment(AttachmentRequest attachmentRequest, Task task) {

        if (attachmentRequest.getName() == null) {
            throw new FlowableIllegalArgumentException("Attachment name is required.");
        }

        Attachment createdAttachment = taskService.createAttachment(attachmentRequest.getType(), task.getId(), task.getProcessInstanceId(), attachmentRequest.getName(),
                attachmentRequest.getDescription(), attachmentRequest.getExternalUrl());

        return restResponseFactory.createAttachmentResponse(createdAttachment);
    }

    protected AttachmentResponse createBinaryAttachment(MultipartHttpServletRequest request, Task task) {

        String name = null;
        String description = null;
        String type = null;

        Map<String, String[]> paramMap = request.getParameterMap();
        for (String parameterName : paramMap.keySet()) {
            if (paramMap.get(parameterName).length > 0) {

View on GitHub (pinned to d6d39ce1c6)