flowable/flowable-engine · error · org.flowable.common.engine.api.FlowableIllegalArgumentException

Cannot use subScopeId together with excludeLocalVariables

Error message

Cannot use subScopeId together with excludeLocalVariables

What it means

HistoricVariableInstanceQuery.subScopeId() throws FlowableIllegalArgumentException when excludeLocalVariables was already enabled on the query. Sub-scope filtering is a local-variable-oriented concept and is mutually exclusive with excluding local variables, so combining them is an invalid query state the library refuses to build.

Solutions

1. Remove the excludeLocalVariables() call when filtering by subScopeId.
2. Choose one filtering strategy: either subScopeId-based local variable lookup or excludeLocalVariables.
3. If both options can be requested by callers, validate and reject the combination in your own code with a clear message.
4. If a scope/task id is known, consider taskId/executionId filters, which also conflict with excludeLocalVariables.

Example fix

// before
query.excludeLocalVariables().subScopeId("mySubScope");

// after
query.subScopeId("mySubScope"); // drop excludeLocalVariables

if (useExcludeLocalVariables && subScopeId != null) {
    throw new IllegalArgumentException("excludeLocalVariables cannot be combined with subScopeId");
}

try {
    query.subScopeId(subScopeId);
} catch (FlowableIllegalArgumentException e) {
    throw new IllegalStateException("Query configured with excludeLocalVariables; subScopeId not allowed", e);
}

When it happens

Trigger: Calling query.excludeLocalVariables() followed by query.subScopeId("...") — in any order, since subScopeId checks the excludeLocalVariables flag which excludeLocalVariables() sets; the flag is already true when subScopeId is invoked.

Common situations: Building a shared query configurator that always calls excludeLocalVariables() and then conditionally adds subScopeId; copying query options from another query that had excludeLocalVariables set.

Related errors

• Cannot use subScopeId together with excludeLocalVariables
• Cannot use taskId together with excludeLocalVariables
• appsDefinitionIds is null
• Booleans and null cannot be used in 'greater than' condition
• Booleans and null cannot be used in 'greater than or equal'…

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/HistoricVariableInstanceQueryImpl.java:269

    @Override
    public HistoricVariableInstanceQuery scopeId(String scopeId) {
        this.scopeId = scopeId;
        return this;
    }
    
    @Override
    public HistoricVariableInstanceQuery scopeIds(Collection<String> scopeIds) {
        if (scopeIds == null || scopeIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("scopeIds is empty");
        }
        this.scopeIds = scopeIds;
        return this;
    }

    @Override
    public HistoricVariableInstanceQuery subScopeId(String subScopeId) {
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use subScopeId together with excludeLocalVariables");
        }

        this.subScopeId = subScopeId;
        return this;
    }
    
    @Override
    public HistoricVariableInstanceQuery scopeType(String scopeType) {
        this.scopeType = scopeType;
        return this;
    }

    @Override
    public HistoricVariableInstanceQuery excludeLocalVariables() {
        if (taskId != null) {
            throw new FlowableIllegalArgumentException("Cannot use taskId together with excludeLocalVariables");
        }
        if (taskIds != null) {

View on GitHub (pinned to d6d39ce1c6)