flowable/flowable-engine · error · FlowableIllegalArgumentException

Illegal action: '${action}'.

Error message

Illegal action: '${action}'.

What it means

The bulk-delete endpoint accepts a request with an 'action' field, and only a specific delete action is legal. If the action string is anything else, bulkDeleteProcessInstances throws FlowableIllegalArgumentException listing the offending action value. This guards against unsupported bulk operations being silently ignored.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/ProcessInstanceCollectionResource.java:469

        }
    }

    @ApiOperation(value = "Bulk delete process instances", tags = { "Process Instances" }, nickname = "deleteProcessInstances", code = 204)
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Indicates the bulk of process instances was found and deleted. Response body is left empty intentionally."),
            @ApiResponse(code = 404, message = "Indicates at least one requested process instance was not found.")
    })
    @PostMapping(value = "/runtime/process-instances/delete")
    @ResponseStatus(value = HttpStatus.NO_CONTENT)
    public void bulkDeleteProcessInstances(@RequestBody BulkDeleteInstancesRestActionRequest request) {
        if (BulkDeleteInstancesRestActionRequest.DELETE_ACTION.equals(request.getAction())) {

            if (restApiInterceptor != null) {
                restApiInterceptor.bulkDeleteProcessInstances(request.getInstanceIds());
            }
            runtimeService.bulkDeleteProcessInstances(request.getInstanceIds(), request.getDeleteReason());
        } else {
            throw new FlowableIllegalArgumentException("Illegal action: '" + request.getAction() + "'.");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set "action" to the supported value used by this endpoint's delete request (match the constant in the Flowable REST model/DTO).
2. Check your client DTO's action field against the Flowable version you run; enum values differ across releases.
3. If you meant a different operation (suspend/activate), call the corresponding dedicated endpoint instead of the bulk-delete one.

Example fix

// before
POST /runtime/process-instances/delete {"action":"remove","instanceIds":["pi-1"]}
// after
POST /runtime/process-instances/delete {"action":"delete","instanceIds":["pi-1"],"deleteReason":"cleanup"}

if (!"delete".equals(bulkRequest.getAction())) {
    throw new IllegalArgumentException("bulk delete only supports action=delete, got: " + bulkRequest.getAction());
}

try {
    restClient.bulkDeleteProcessInstances(req);
} catch (HttpClientErrorException.BadRequest e) {
    if (e.getResponseBodyAsString().startsWith("Illegal action:")) {
        // fix action enum value
    }
}

When it happens

Trigger: POST /runtime/process-instances/delete (or the bulk-delete sub-resource) with a body whose "action" is not the supported delete value, e.g. {"action":"suspend","instanceIds":["..."]}. Thrown at ProcessInstanceCollectionResource.java:469.

Common situations: Copying a request body from a different endpoint (e.g. job or task actions); misspelling the action enum; client library versions where the action constant changed between Flowable releases.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Illegal action: '" + request.getAction() + "'.
• Illegal action: '${request.getAction()}'.
• Unsupported variable query operation: " + variable.getVariab
• ${cause}
• Error exporting diagram

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