flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot use executionIds together with excludeLocalVariables

Error message

Cannot use executionIds together with excludeLocalVariables

What it means

Like executionId, executionIds(Set<String>) cannot be combined with excludeLocalVariables. Flowable considers excluding local variables while filtering by execution ids contradictory, and throws FlowableIllegalArgumentException during query construction.

Solutions

Remove excludeLocalVariables() when filtering by executionIds
Extract a separate query path that does not set the exclusion flag
Post-filter results by variable scope in application code instead

Example fix

// before
query.excludeLocalVariables().executionIds(ids);
// after
query.executionIds(ids);

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean isCompatibleQuery(VariableInstanceQuery q) { return q != null; } // guard the flag combination at call site

Try / catch

try {
    query.executionIds(executionIds);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("excludeLocalVariables")) {
        query = createBaseQuery().executionIds(executionIds);
    } else { throw e; }
}

Prevention

Keep exclusion flags and id filters in mutually exclusive builder paths
Code-review shared query helpers for unconditional flag setting
Test both call orders (flag-then-filter and filter-then-flag) since checks run on both

When it happens

Trigger: Calling variableInstanceQuery.excludeLocalVariables().executionIds(ids) (in either order) on the VariableInstanceQuery API.

Common situations: Reusing a shared query-building helper that unconditionally calls excludeLocalVariables, then adding an executionIds filter in a specific code path.

Related errors

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

Appendix: source

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

            throw new FlowableIllegalArgumentException("Execution id is null");
        }
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use executionId together with excludeLocalVariables");
        }
        this.executionId = executionId;
        return this;
    }

    @Override
    public VariableInstanceQueryImpl executionIds(Set<String> executionIds) {
        if (executionIds == null) {
            throw new FlowableIllegalArgumentException("executionIds is null");
        }
        if (executionIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of executionIds is empty");
        }
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use executionIds together with excludeLocalVariables");
        }
        this.executionIds = executionIds;
        return this;
    }

    public VariableInstanceQuery activityInstanceId(String activityInstanceId) {
        this.activityInstanceId = activityInstanceId;
        return this;
    }

    @Override
    public VariableInstanceQuery taskId(String taskId) {
        if (taskId == null) {
            throw new FlowableIllegalArgumentException("taskId is null");
        }
        if (excludeTaskRelated) {
            throw new FlowableIllegalArgumentException("Cannot use taskId together with excludeTaskVariables");
        }

View on GitHub (pinned to d6d39ce1c6)