flowable/flowable-engine · error · FlowableIllegalArgumentException

parentScopeIds is null or empty

Error message

parentScopeIds is null or empty

What it means

Flowable's CaseInstanceQueryImpl throws FlowableIllegalArgumentException when caseInstanceParentScopeIds(Set<String>) is called with a null or empty set. An empty IN-list has no valid SQL semantics for this filter, so the query API validates the argument up front. At least one parent scope id must be supplied.

Source

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

    }

    @Override
    public CaseInstanceQuery 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 CaseInstanceQuery 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 CaseInstanceQueryImpl caseInstanceBusinessKey(String businessKey) {
        if (businessKey == null) {
            throw new FlowableIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessKey = businessKey;
        } else {
            this.businessKey = businessKey;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Only call the method when the set contains at least one id; otherwise skip the criterion
2. Validate the upstream collection (parent scope lookup) that should have produced the ids
3. Fall back to caseInstanceParentScopeId for the single-id case if that is what you have
4. If no filtering is desired, do not add the parent-scope criterion at all

Example fix

// before
query.caseInstanceParentScopeIds(parentScopeIds); // may be null/empty
// after
if (parentScopeIds != null && !parentScopeIds.isEmpty()) {
    query.caseInstanceParentScopeIds(parentScopeIds);
}

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) {
    log.warn("Invalid parent scope ids: {}", e.getMessage());
    throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "parentScopeIds must not be empty");
}

When it happens

Trigger: Calling caseInstanceParentScopeIds(null), an empty Set/Collections.emptySet(), or a set derived from filtering that ended up empty before executing the case instance query.

Common situations: Batch queries where the parent scope ids were collected from a prior query that returned no rows; passing an empty HashSet initialized but never filled; refactoring from single caseInstanceParentScopeId to plural and forgetting to populate; parallel test runs with no scope data.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• rootScopeIds is null or empty
• parentScopeId is null
• caseInstanceId is null
• variable name is null
• caseInstanceId is null

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