flowable/flowable-engine · warning · FlowableIllegalArgumentException

A group or a user is required to create an identity link.

Error message

A group or a user is required to create an identity link.

What it means

POST /runtime/tasks/{taskId}/identitylinks requires at least one of 'user' or 'group' in the payload. FlowableIllegalArgumentException is thrown when both are null because an identity link must point at a user or a group.

Solutions

1. Include exactly one of 'user' or 'group' in the request body
2. Fix field names to match the API ('user' and 'group', not 'userId'/'groupId')
3. Add client-side validation requiring a selection before submission

Example fix

// before
{"type": "candidate"}
// after
{"type": "candidate", "user": "kermit"}

if (!payload.user && !payload.group) {
  throw new Error('identity link requires user or group');
}

try { ... } catch (e) { if (e.status === 400) showFormError('Select a user or a group'); else throw e; }

When it happens

Trigger: POST /runtime/tasks/{taskId}/identitylinks with body like {"type":"candidate"} missing both 'user' and 'group'.

Common situations: Forms that let users pick either user or group but submit without any selection; JSON field name typos (e.g. 'userId' instead of 'user').

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

• Identity link family should be 'users' or 'groups'.
• Identity link family should be 'users' or 'groups'.
• Only one of user or group can be used to create an identity…
• The identity link type is required.
• A group or a user is required to create an identity link.

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

Appendix: source

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

        }

        return restResponseFactory.createRestIdentityLinks(taskService.getIdentityLinksForTask(task.getId()));
    }

    @ApiOperation(value = "Create an identity link on a task", tags = { "Task Identity Links" }, nickname = "createTaskInstanceIdentityLinks",
            notes = "It is possible to add either a user or a group.", code = 201)
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "Indicates the task was found and the identity link was created."),
            @ApiResponse(code = 404, message = "Indicates the requested task was not found or the task does not have the requested identityLink. The status contains additional information about this error.")
    })
    @PostMapping(value = "/runtime/tasks/{taskId}/identitylinks", produces = "application/json")
    @ResponseStatus(HttpStatus.CREATED)
    public RestIdentityLink createIdentityLink(@ApiParam(name = "taskId") @PathVariable("taskId") String taskId, @RequestBody RestIdentityLink identityLink) {

        Task task = getTaskFromRequestWithoutAccessCheck(taskId);

        if (identityLink.getGroup() == null && identityLink.getUser() == null) {
            throw new FlowableIllegalArgumentException("A group or a user is required to create an identity link.");
        }

        if (identityLink.getGroup() != null && identityLink.getUser() != null) {
            throw new FlowableIllegalArgumentException("Only one of user or group can be used to create an identity link.");
        }

        if (identityLink.getType() == null) {
            throw new FlowableIllegalArgumentException("The identity link type is required.");
        }

        if (restApiInterceptor != null) {
            restApiInterceptor.createTaskIdentityLink(task, identityLink);
        }

        if (identityLink.getGroup() != null) {
            taskService.addGroupIdentityLink(task.getId(), identityLink.getGroup(), identityLink.getType());
        } else {
            taskService.addUserIdentityLink(task.getId(), identityLink.getUser(), identityLink.getType());

View on GitHub (pinned to d6d39ce1c6)