flowable/flowable-engine · error · FlowableIllegalArgumentException

Identity link family should be 'users' or 'groups'.

Error message

Identity link family should be 'users' or 'groups'.

What it means

validateIdentityLinkArguments checks the URL path segment selecting the identity-link family. It must be exactly 'users' or 'groups' (the CmmnRestUrls.SEGMENT_IDENTITYLINKS_FAMILY_* constants); anything else throws FlowableIllegalArgumentException("Identity link family should be 'users' or 'groups'.").

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/runtime/caze/CaseInstanceIdentityLinkResource.java:102

        validateIdentityLinkArguments(family, identityId, type);

        IdentityLink link = getIdentityLink(identityId, family, type, caseInstance.getId());

        if (restApiInterceptor != null) {
            restApiInterceptor.deleteCaseInstanceIdentityLink(caseInstance, link);
        }

        if (CmmnRestUrls.SEGMENT_IDENTITYLINKS_FAMILY_GROUPS.equals(family)) {
            runtimeService.deleteGroupIdentityLink(caseInstance.getId(), identityId, type);
            
        } else {
            runtimeService.deleteUserIdentityLink(caseInstance.getId(), identityId, type);
        }
    }

    protected void validateIdentityLinkArguments(String family, String identityId, String type) {
        if (family == null || (!CmmnRestUrls.SEGMENT_IDENTITYLINKS_FAMILY_GROUPS.equals(family) && !CmmnRestUrls.SEGMENT_IDENTITYLINKS_FAMILY_USERS.equals(family))) {
            throw new FlowableIllegalArgumentException("Identity link family should be 'users' or 'groups'.");
        }
        if (identityId == null) {
            throw new FlowableIllegalArgumentException("IdentityId is required.");
        }
        if (type == null) {
            throw new FlowableIllegalArgumentException("Type is required.");
        }
    }

    protected IdentityLink getIdentityLink(String identityId, String family, String type, String caseInstanceId) {
        // Perhaps it would be better to offer getting a single identity link
        // from the API
        List<IdentityLink> allLinks = runtimeService.getIdentityLinksForCaseInstance(caseInstanceId);
        for (IdentityLink link : allLinks) {
            if (CmmnRestUrls.SEGMENT_IDENTITYLINKS_FAMILY_USERS.equals(family) && identityId.equals(link.getUserId()) && link.getType().equals(type)) {
                return link;
            
            } else if (CmmnRestUrls.SEGMENT_IDENTITYLINKS_FAMILY_GROUPS.equals(family) && identityId.equals(link.getGroupId()) && link.getType().equals(type)) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Use the exact path segments 'users' or 'groups' in the URL.
2. Build URLs with CmmnRestUrls.SEGMENT_IDENTITYLINKS_FAMILY_USERS / _GROUPS constants instead of string literals.
3. Fix typos and ensure lowercase segments.

Example fix

// before
DELETE /cmmn-runtime/case-instances/case-1/identitylinks/user/kermit/participant
// after
DELETE /cmmn-runtime/case-instances/case-1/identitylinks/users/kermit/participant

// Java
if (!"users".equals(family) && !"groups".equals(family)) {
    throw new IllegalArgumentException("family must be users or groups");
}

try { restTemplate.exchange(url, HttpMethod.DELETE, null, Void.class, vars); }
catch (HttpClientErrorException e) { /* 400: family must be users or groups */ }

When it happens

Trigger: GET or DELETE /cmmn-runtime/case-instances/{id}/identitylinks/{family}/{identityId}/{type} where {family} is not 'users' or 'groups' — e.g. 'user', 'group', 'members', or a typo.

Common situations: Singular/plural mix-ups in hand-built URLs; confusing this endpoint with task identity-links paths; case-sensitivity mistakes ('Users').

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• A group or a user is required to create an identity link.
• Only one of user or group can be used to create an identity
• User or group are required.
• Only one value of user or group is supported.
• The identity link type is required.

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