flowable/flowable-engine · error · FlowableIllegalArgumentException

Either set the user id or the group id for an identity…

Error message

Either set the user id or the group id for an identity link, but not both the same time.

What it means

createIdentityLinkType allows an identity link to reference either a user or a group, not both. If both userId and groupId are non-null, it throws FlowableIllegalArgumentException before creating the link. If both are null, the call is a silent no-op.

Solutions

1. Set exactly one of userId or groupId; create two separate identity links if both are genuinely needed.
2. Add client-side validation to reject payloads with both fields set.
3. In UI code, make the user/group selection mutually exclusive or clear the other field on selection.

Example fix

// before
runtimeService.addUserIdentityLinkToProcessInstance(piId, userId, groupId, "participant"); // both set
// after
if (userId != null) {
    runtimeService.addUserIdentityLinkToProcessInstance(piId, userId, null, "participant");
} else {
    runtimeService.addGroupIdentityLinkToProcessInstance(piId, groupId, "participant");
}

if (userId != null && groupId != null) {
    throw new IllegalArgumentException("Set user or group, not both");
}

When it happens

Trigger: Calling an add-identity-link command/API for a process instance with both userId and groupId populated (e.g. UI sending both fields, or code that sets defaults for both).

Common situations: Front-end forms with both 'user' and 'group' inputs filled; copying parameters into both arguments; framework binding that populates both request fields; confusion between Flowable identity link and other APIs that accept both.

Related errors

• A group or a user is required to create an identity link.
• A process instance id is required, but the provided id '" +…
• A process instance id is required, but the provided id
• Candidate group list is empty
• Candidate group list is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessInstanceIdentityLinkCmd.java:77

    /**
     * Creates a new identity link entry for the given process instance, which can either be a user or group based one, but not both the same time.
     * If both the user and group ids are null, no new identity link is created.
     *
     * @param commandContext the command context within which to perform the identity link creation
     * @param processInstanceId the id of the process instance to create an identity link for
     * @param userId the user id if this is a user based identity link, otherwise null
     * @param groupId the group id if this is a group based identity link, otherwise null
     * @param identityType the type of identity link (e.g. owner or assignee, etc)
     */
    protected void createIdentityLinkType(CommandContext commandContext, String processInstanceId, String userId, String groupId, String identityType) {
        // if both user and group ids are null, don't create an identity link
        if (userId == null && groupId == null) {
            return;
        }

        // if both are set the same time, throw an exception as this is not allowed
        if (userId != null && groupId != null) {
            throw new FlowableIllegalArgumentException("Either set the user id or the group id for an identity link, but not both the same time.");
        }

        ExecutionEntity processInstanceEntity = getProcessInstanceEntity(commandContext, processInstanceId);
        IdentityLinkUtil.createProcessInstanceIdentityLink(processInstanceEntity, userId, groupId, identityType);
    }
}

View on GitHub (pinned to d6d39ce1c6)