flowable/flowable-engine · error · FlowableIllegalArgumentException

identityLinkType is null

Error message

identityLinkType is null

What it means

HistoricCaseInstanceQueryImpl.involvedUser(String userId, String identityLinkType) throws FlowableIllegalArgumentException("identityLinkType is null") when the identity link type parameter is null. The type (e.g. participant, owner, assignee) is required to build the identity-link join predicate.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:1098

    public HistoricCaseInstanceQuery 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 HistoricCaseInstanceQuery 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 HistoricCaseInstanceQuery 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 non-null identity link type constant (e.g. from IdentityLinkType).
  2. Validate/normalize the link type string before calling; reject unknown values early.
  3. If any link type should match, use plain involvedUser(userId) instead of the two-arg overload.
  4. Fix enum/config mappings so they never yield null for known inputs.

Example fix

// before
query.involvedUser(userId, linkType); // linkType may be null
// after
if (userId != null && linkType != null) {
    query.involvedUser(userId, linkType);
}
Defensive patterns

Strategy: validation

Validate before calling

if (identityLinkType == null || identityLinkType.isEmpty()) {
    throw new IllegalArgumentException("identityLinkType is required");
}
query.involvedUser(userId, identityLinkType);

Type guard

boolean isKnownLinkType(String type) {
    return IdentityLinkType.PARTICIPANT.equals(type)
        || IdentityLinkType.OWNER.equals(type)
        || IdentityLinkType.ASSIGNEE.equals(type);
}

Try / catch

try {
    query.involvedUser(userId, identityLinkType);
} catch (FlowableIllegalArgumentException e) {
    if ("identityLinkType is null".equals(e.getMessage())) {
        // use single-arg involvedUser(userId) or rethrow with context
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Calling involvedUser(userId, null) on a HistoricCaseInstanceQuery — usually when the link type is read from config/enum mapping that returned null.

Common situations: An enum-to-string lookup or constants class returned null; a typo in the link-type constant reference; API clients passing an unrecognized type that got normalized to null.

Related errors

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