flowable/flowable-engine · error · FlowableIllegalArgumentException

parentScopeIds is null or empty

Error message

parentScopeIds is null or empty

What it means

ProcessInstanceQueryImpl.processInstanceParentScopeIds(Set<String>) filters process instances by parent scope IDs. Flowable throws FlowableIllegalArgumentException for a null or empty set, since an empty ID set yields an invalid empty IN clause in the generated SQL. The validation happens immediately in the fluent query method.

Solutions

1. Call processInstanceParentScopeIds only with a non-empty set; otherwise omit the filter
2. Obtain valid parent scope IDs (e.g., via runtimeService) before building the query
3. Fix upstream parent-execution resolution logic
4. Catch FlowableIllegalArgumentException and handle the 'no parents' case explicitly

Example fix

// before
query.processInstanceParentScopeIds(parentScopeIds);
// after
if (parentScopeIds != null && !parentScopeIds.isEmpty()) {
    query.processInstanceParentScopeIds(parentScopeIds);
} else {
    // handle no parent scopes (e.g., top-level query)
}

if (parentScopeIds == null || parentScopeIds.isEmpty()) {
    throw new IllegalArgumentException("At least one parent scope id is required");
}

boolean hasParentScopeIds = parentScopeIds != null && !parentScopeIds.isEmpty();

try {
    query.processInstanceParentScopeIds(parentScopeIds);
} catch (FlowableIllegalArgumentException e) {
    // treat as top-level query or empty result
}

When it happens

Trigger: Calling processInstanceParentScopeIds(null) or with an empty set, commonly when parent scope IDs were derived from a parent execution that no longer exists or from an empty collection of parent executions.

Common situations: Child-process queries where the parent lookup returned nothing; recursive hierarchy queries that hit a top-level instance with no parent; refactors that changed which collection gets passed.

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
• callbackIds is null or empty
• Involved groups are empty
• variableNames are null or empty
• at least one of userId or groups must be provided

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:741

            this.rootScopeIds = rootScopeIds;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceParentScopeId(String parentId) {
        if (inOrStatement) {
            this.currentOrQueryObject.parentScopeId = parentId;
        } else {
            this.parentScopeId = parentId;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceParentScopeIds(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 ProcessInstanceQuery activeActivityId(String activityId) {
        if (inOrStatement) {
            this.currentOrQueryObject.activeActivityId = activityId;
        } else {
            this.activeActivityId = activityId;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)