flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot use taskId together with excludeLocalVariables

Error message

Cannot use taskId together with excludeLocalVariables

What it means

Flowable throws FlowableIllegalArgumentException when excludeLocalVariables() is called on a query that already has a taskId set. Local task variables are exactly what taskId-scoped queries target, so excluding them is contradictory and the builder rejects the combination eagerly.

Solutions

1. Remove excludeLocalVariables() when filtering by taskId
2. If you need non-local variables only, build the query without taskId and use execution/process-instance scoping instead
3. Guard the helper so excludeLocalVariables() is only applied when taskId/taskIds/executionId/subScopeId are all unset

Example fix

// before
query.taskId(taskId);
query.excludeLocalVariables(); // throws
// after
query.taskId(taskId); // task-local variables kept
// or for non-local variables only:
query.executionId(executionId);
query.excludeLocalVariables();

if (taskId != null && excludeLocal) {
    throw new IllegalArgumentException("excludeLocalVariables cannot be used with taskId");
}
query.taskId(taskId);

try {
    query.taskId(taskId).excludeLocalVariables();
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("taskId together with excludeLocalVariables")) {
        query = createQuery().taskId(taskId); // drop the exclusion
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling query.taskId("123").excludeLocalVariables() (or excludeLocalVariables() after any taskId assignment); helper methods that set a taskId for specificity and then unconditionally exclude local variables.

Common situations: Refactors where excludeLocalVariables was added globally to shared query helpers; copying query configuration between execution-based and task-based lookups.

Related errors

• Cannot use subScopeId together with excludeLocalVariables
• Cannot use subScopeId 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/e1178f0b50836701. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/VariableInstanceQueryImpl.java:263

    @Override
    public VariableInstanceQuery subScopeId(String subScopeId) {
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use subScopeId together with excludeLocalVariables");
        }
        this.subScopeId = subScopeId;
        return this;
    }
    
    @Override
    public VariableInstanceQuery scopeType(String scopeType) {
        this.scopeType = scopeType;
        return this;
    }

    @Override
    public VariableInstanceQuery excludeLocalVariables() {
        if (taskId != null) {
            throw new FlowableIllegalArgumentException("Cannot use taskId together with excludeLocalVariables");
        }
        if (taskIds != null) {
            throw new FlowableIllegalArgumentException("Cannot use taskIds together with excludeLocalVariables");
        }
        if (executionId != null) {
            throw new FlowableIllegalArgumentException("Cannot use executionId together with excludeLocalVariables");
        }
        if (subScopeId != null) {
            throw new FlowableIllegalArgumentException("Cannot use subScopeId together with excludeLocalVariables");
        }
        excludeLocalVariables = true;
        return this;
    }

    protected void ensureVariablesInitialized() {
        if (this.queryVariableValue != null) {
            queryVariableValue.initialize(variableServiceConfiguration);
        }

View on GitHub (pinned to d6d39ce1c6)