flowable/flowable-engine · error · FlowableIllegalArgumentException

Failed to serialize to a AttachmentRequest instance

Error message

Failed to serialize to a AttachmentRequest instance

What it means

POSTing a task attachment as JSON requires the body to deserialize into an AttachmentRequest. If Jackson cannot parse the payload (invalid JSON, wrong types, wrong Content-Type), Flowable throws FlowableIllegalArgumentException("Failed to serialize to a AttachmentRequest instance") wrapping the parse exception.

Source

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

    @PostMapping(value = "/runtime/tasks/{taskId}/attachments", produces = "application/json", consumes = {"application/json", "multipart/form-data"})
    @ResponseStatus(HttpStatus.CREATED)
    public AttachmentResponse createAttachment(@ApiParam(name = "taskId") @PathVariable String taskId, HttpServletRequest request) {

        AttachmentResponse result = null;
        Task task = getTaskFromRequestWithoutAccessCheck(taskId);
        if (restApiInterceptor != null) {
            restApiInterceptor.createTaskAttachment(task);
        }
        if (request instanceof MultipartHttpServletRequest) {
            result = createBinaryAttachment((MultipartHttpServletRequest) request, task);
        } else {

            AttachmentRequest attachmentRequest = null;
            try {
                attachmentRequest = objectMapper.readValue(request.getInputStream(), AttachmentRequest.class);

            } 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.");
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the JSON body locally before sending.
2. Send Content-Type: application/json with a body like {"name":"doc","description":"...","externalUrl":"..."}.
3. For binary uploads use the binary-attachment endpoint/multipart form instead of the JSON branch.
4. Check the server log cause for the exact Jackson error and fix the offending field type.

Example fix

// before
-d 'name=report'  // not JSON

// after
-H 'Content-Type: application/json' -d '{"name":"report","description":"Q3 report"}'

const payload = { name: 'doc', description: 'd', externalUrl: 'https://...' };
const json = JSON.stringify(payload);
JSON.parse(json); // local parse check
await post(url, json, { headers: { 'Content-Type': 'application/json' } });

function isAttachmentRequest(v) {
  return v != null && typeof v.name === 'string'
    && (v.description === undefined || typeof v.description === 'string')
    && (v.externalUrl === undefined || typeof v.externalUrl === 'string');
}

try {
  await api.post(`/tasks/${taskId}/attachments`, payload);
} catch (e) {
  if (/Failed to serialize to a AttachmentRequest/.test(e.response?.data?.message || '')) {
    // fix JSON structure/types before retrying
  }
}

When it happens

Trigger: POST /runtime/tasks/{taskId}/attachments with malformed JSON, non-JSON payload sent as application/json, or fields whose types do not match AttachmentRequest (name/description/externalUrl/type as non-strings).

Common situations: Multipart vs JSON confusion (JSON branch expects a JSON body, not form-data), hand-built JSON with unescaped quotes, missing Content-Type header, truncated uploads.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• request body could not be transformed to a RestVariable inst
• Error reading app resource
• Error converting request body to RestVariable instance
• Could not deserialize event to json
• Failed to serialize to a RestVariable instance

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