flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot combine subScopeIds with withoutSubScopeId in the…

Error message

Cannot combine subScopeIds with withoutSubScopeId in the same query

What it means

InternalVariableInstanceQueryImpl throws this when subScopeIds(Collection) is called after withoutSubScopeId() was already set. Filtering for variables under a set of subScopeIds conflicts with filtering for variables that have no subScopeId at all, so the combination is rejected.

Solutions

Use either withoutSubScopeId() or subScopeIds(...) — never both on one query.
If the collection may be empty and you intended 'no subScopeId', call withoutSubScopeId() only.
Create a new query instance when switching filtering strategy.

Example fix

// before
query.withoutSubScopeId();
query.subScopeIds(ids); // throws

// after
if (ids.isEmpty()) {
    query.withoutSubScopeId();
} else {
    query.subScopeIds(ids);
}

Defensive patterns

Strategy: validation

Validate before calling

if (useWithoutSubScope && subScopeIds != null && !subScopeIds.isEmpty()) {
    throw new IllegalStateException("Choose either subScopeIds or withoutSubScopeId, not both");
}

Prevention

Branch on collection emptiness: empty list -> withoutSubScopeId(), otherwise subScopeIds(...).
Build queries fresh for each request.
Document the mutual exclusion in your query-builder API.

When it happens

Trigger: Calling query.withoutSubScopeId() and then query.subScopeIds(Arrays.asList("a","b")); guard at InternalVariableInstanceQueryImpl.java:160 checks the withoutSubScopeId flag.

Common situations: Programmatic query builders collecting a list of scope IDs while another code path has already flagged 'exclude any subScopeId'; refactoring code from withoutSubScopeId() to a list filter without resetting the query.

Related errors

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/InternalVariableInstanceQueryImpl.java:160

    @Override
    public InternalVariableInstanceQuery subScopeId(String subScopeId) {
        if (StringUtils.isEmpty(subScopeId)) {
            throw new FlowableIllegalArgumentException("subScopeId is empty");
        }

        if (withoutSubScopeId) {
            throw new FlowableIllegalArgumentException("Cannot combine subScopeId(String) with withoutSubScopeId() in the same query");
        }

        this.subScopeId = subScopeId;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery subScopeIds(Collection<String> subScopeIds) {
        if (withoutSubScopeId) {
            throw new FlowableIllegalArgumentException("Cannot combine subScopeIds with withoutSubScopeId in the same query");
        }

        this.subScopeIds = subScopeIds;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery withoutSubScopeId() {
        if (subScopeId != null) {
            throw new FlowableIllegalArgumentException("Cannot combine withoutSubScopeId() with subScopeId(String) in the same query");
        }
        this.withoutSubScopeId = true;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery scopeType(String scopeType) {
        if (StringUtils.isEmpty(scopeType)) {

View on GitHub (pinned to d6d39ce1c6)