flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot combine subScopeId(String) with withoutSubScopeId()…

Error message

Cannot combine subScopeId(String) with withoutSubScopeId() in the same query

What it means

Flowable's InternalVariableInstanceQueryImpl throws this when subScopeId(String) is called after withoutSubScopeId() has already been set. These two filters are logically contradictory: one targets variables under a specific sub-scope, the other targets variables with no sub-scope, so no query could satisfy both.

Solutions

Decide which filter you need and call only one of subScopeId(...) or withoutSubScopeId() per query.
Build a fresh InternalVariableInstanceQuery instead of reusing a configured one.
Wrap conditional filter addition in if/else so the two options are mutually exclusive.

Example fix

// before
query.withoutSubScopeId();
query.subScopeId("subScope-1"); // throws

// after
query.subScopeId("subScope-1"); // pick only one filter

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Encapsulate subScope filtering in one builder method that applies exactly one of the two options.
Never reuse a configured query object across code paths.
Centralize filter addition so mutual exclusion is enforced in one place.

When it happens

Trigger: Calling query.withoutSubScopeId() followed by query.subScopeId("someId") on the same InternalVariableInstanceQuery instance; the guard at InternalVariableInstanceQueryImpl.java:150 fires because the withoutSubScopeId flag is already true.

Common situations: Dynamically building query filters where optional criteria are added conditionally and both a 'has subScopeId' and 'has no subScopeId' branch can run for the same query object; reusing a cached/shared query instance across code paths.

Related errors

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

Appendix: source

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

        }
        this.scopeId = scopeId;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery scopeIds(Collection<String> scopeIds) {
        this.scopeIds = scopeIds;
        return this;
    }

    @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() {

View on GitHub (pinned to d6d39ce1c6)