flowable/flowable-engine · error · FlowableIllegalArgumentException

parentScopeIds is null or empty

Error message

parentScopeIds is null or empty

What it means

HistoricCaseInstanceQueryImpl.caseInstanceParentScopeIds() validates its argument before storing it in the query state. Flowable throws FlowableIllegalArgumentException when the caller passes a null or empty Set of parent scope ids, because a null/empty set cannot be translated into a meaningful SQL IN clause and would silently return wrong results. The query is never built; the error is thrown immediately at call time, before executeList().

Source

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

    }

    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceParentScopeId(String parentScopeId) {
        if (parentScopeId == null) {
            throw new FlowableIllegalArgumentException("parentScopeId is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.parentScopeId = parentScopeId;
        } else {
            this.parentScopeId = parentScopeId;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQuery caseInstanceParentScopeIds(Set<String> parentScopeIds) {
        if (parentScopeIds == null || parentScopeIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("parentScopeIds is null or empty");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.parentScopeIds = parentScopeIds;
        } else {
            this.parentScopeIds = parentScopeIds;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceBusinessStatus(String businessStatus) {
        if (businessStatus == null) {
            throw new FlowableIllegalArgumentException("Business status is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessStatus = businessStatus;
        } else {
            this.businessStatus = businessStatus;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the Set<String> passed to caseInstanceParentScopeIds contains at least one parent scope id before calling the query method.
2. If the collection is legitimately empty, skip calling caseInstanceParentScopeIds entirely so no parent-scope filter is applied.
3. If null means 'no filtering intended', guard the call: only invoke the setter when ids != null && !ids.isEmpty().
4. Catch FlowableIllegalArgumentException around query building if arguments are user-supplied, and return a 400-style validation error.

Example fix

// before
query.caseInstanceParentScopeIds(parentIds);
// after
if (parentIds != null && !parentIds.isEmpty()) {
    query.caseInstanceParentScopeIds(parentIds);
}

if (parentScopeIds == null || parentScopeIds.isEmpty()) {
    throw new IllegalArgumentException("parentScopeIds must contain at least one id");
}
query.caseInstanceParentScopeIds(parentScopeIds);

boolean hasParentScopeIds(Set<String> ids) {
    return ids != null && !ids.isEmpty();
}

try {
    query.caseInstanceParentScopeIds(parentScopeIds);
} catch (FlowableIllegalArgumentException e) {
    throw new InvalidRequestException("parentScopeIds: " + e.getMessage());
}

When it happens

Trigger: Calling historicCaseInstanceQuery.caseInstanceParentScopeIds(null) or caseInstanceParentScopeIds(new HashSet<>()) (empty set). Also thrown inside an or() block via the currentOrQueryObject path since validation happens before the inOrStatement branch.

Common situations: Building query filters from dynamic data where the parent scope id collection comes from an optional configuration, a REST request parameter, or an upstream lookup that returned nothing; developers pass the result straight through without checking null/empty.

Related errors

• query is null
• Business status is null
• Case definition keys is null
• tenant id is null
• variableNames is null or empty

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