flowable/flowable-engine · error · FlowableIllegalArgumentException

identityLinkType is null

Error message

identityLinkType is null

What it means

CaseInstanceQueryImpl.involvedUser(String userId, String identityLinkType) throws FlowableIllegalArgumentException when identityLinkType is null. The identity link type selects which kind of involvement (participant, owner, etc.) is matched, so a null type cannot form a valid filter.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceQueryImpl.java:828

    public CaseInstanceQuery involvedUser(String userId) {
        if (userId == null) {
            throw new FlowableIllegalArgumentException("involvedUser is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.involvedUser = userId;
        } else {
            this.involvedUser = userId;
        }
        return this;
    }
    
    @Override
    public CaseInstanceQuery involvedUser(String userId, String identityLinkType) {
        if (userId == null) {
            throw new FlowableIllegalArgumentException("userId is null");
        }
        if (identityLinkType == null) {
            throw new FlowableIllegalArgumentException("identityLinkType is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.involvedUserIdentityLink = new IdentityLinkQueryObject(userId, null, identityLinkType);
        } else {
            this.involvedUserIdentityLink = new IdentityLinkQueryObject(userId, null, identityLinkType);
        }
        return this;
    }
    
    @Override
    public CaseInstanceQuery involvedGroup(String groupId, String identityLinkType) {
        if (groupId == null) {
            throw new FlowableIllegalArgumentException("groupId is null");
        }
        if (identityLinkType == null) {
            throw new FlowableIllegalArgumentException("identityLinkType is null");
        }
        if (inOrStatement) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass a valid identity link type string (e.g. "participant", "owner") and validate it is non-null before the call.
  2. If the type is optional, only apply the involvedUser filter when a type is chosen, otherwise fall back to the single-argument involvedUser(userId).
  3. Fix the enum/string mapping so the type is always provided.
  4. Reject the query request with a validation error naming the missing identityLinkType.

Example fix

// before
query.involvedUser(userId, filter.getRelationType());
// after
if (filter.getRelationType() != null) {
    query.involvedUser(userId, filter.getRelationType());
} else {
    query.involvedUser(userId);
}
Defensive patterns

Strategy: validation

Validate before calling

if (identityLinkType == null) {
    throw new IllegalArgumentException("identityLinkType required (e.g. participant, owner)");
}
query.involvedUser(userId, identityLinkType);

Type guard

boolean isValidIdentityLinkType(String type) {
    return type != null && Set.of("participant", "owner", "candidate").contains(type);
}

Try / catch

try {
    query.involvedUser(userId, identityLinkType);
} catch (FlowableIllegalArgumentException e) {
    log.warn("identityLinkType missing, falling back to plain involvedUser");
    query.involvedUser(userId);
}

Prevention

When it happens

Trigger: Calling involvedUser("someUser", null), usually because the identity link type came from an unset enum-to-string mapping, missing request parameter, or uninitialized constant.

Common situations: Admin search screens with a 'relation type' dropdown left unselected; refactors where the type constant was renamed/removed; passing IdentityLinkType enum values without mapping them to their string representation.

Related errors

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