flowable/flowable-engine · error · FlowableIllegalArgumentException

parentScopeIds is null or empty

Error message

parentScopeIds is null or empty

What it means

HistoricProcessInstanceQuery.processInstanceParentScopeIds(Set<String>) requires a non-null, non-empty set of parent scope ids. Flowable throws FlowableIllegalArgumentException when parentScopeIds is null or empty, since an empty IN filter is meaningless. The check runs eagerly at query-build time.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/HistoricProcessInstanceQueryImpl.java:401

            this.rootScopeIds = rootScopeIds;
        }
        return this;
    }

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Populate the set with at least one parent scope id before calling
2. Guard with null/isEmpty check and omit the criterion or take an alternate query path when absent
3. Return an empty result early if no parent scopes apply
4. Confirm the parent-instance lookup used to derive the ids is correct

Example fix

// before
query.processInstanceParentScopeIds(parentScopeIds); // throws when null or empty
// after
if (parentScopeIds != null && !parentScopeIds.isEmpty()) {
    query.processInstanceParentScopeIds(parentScopeIds);
}

if (parentScopeIds == null || parentScopeIds.isEmpty()) {
    throw new IllegalArgumentException("parentScopeIds must be non-null and non-empty");
}
query.processInstanceParentScopeIds(parentScopeIds);

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

try {
    query.processInstanceParentScopeIds(parentScopeIds);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Skipping parent scope filter: {}", e.getMessage());
    // continue with query minus this criterion
}

When it happens

Trigger: Calling processInstanceParentScopeIds(parentScopeIds) with a null reference or an empty set (e.g. new HashSet<>() or a collection emptied by upstream filtering).

Common situations: Queries on child process instances/scope hierarchy where the parent scope ids come from a nullable API parameter or from resolving a parent instance that returned none.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• rootScopeIds is null or empty
• Provided batch types must be provided and not empty
• rootScopeIds is null or empty
• Set of process instance ids is null
• Set of process instance ids is empty

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