flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot use taskIds together with excludeLocalVariables

Error message

Cannot use taskIds together with excludeLocalVariables

What it means

taskId(String) also cannot be combined with excludeLocalVariables. Flowable throws FlowableIllegalArgumentException when the local-variable exclusion flag is set while targeting a specific task, since the combination is deemed invalid. (Note the message says 'taskIds' — a known message typo — but it is raised from the singular taskId() method.)

Solutions

1. Remove excludeLocalVariables() when filtering by taskId
2. Branch the query construction so the exclusion flag is only set for execution-scoped queries
3. Filter local vs non-local variables in application code after fetching

Example fix

// before
query.excludeLocalVariables().taskId(taskId);
// after
query.taskId(taskId);

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

boolean isCompatibleQuery(VariableInstanceQuery q) { return q != null; } // enforce flag exclusivity at call site

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

When it happens

Trigger: Calling variableInstanceQuery.excludeLocalVariables().taskId(id) in either order on the VariableInstanceQuery API.

Common situations: Shared query builder that always applies excludeLocalVariables for 'scope variable' queries, then a caller adds a taskId filter.

Related errors

• Cannot use executionId together with excludeLocalVariables
• Cannot use executionIds together with excludeLocalVariables
• Cannot use taskId together with excludeTaskVariables
• Cannot use taskIds together with excludeTaskVariables
• executionIds is null

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

Appendix: source

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

        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");
        }
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use taskIds together with excludeLocalVariables");
        }
        this.taskId = taskId;
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)