flowable/flowable-engine · error · FlowableIllegalArgumentException

Cannot use taskIds together with excludeTaskVariables

Error message

Cannot use taskIds together with excludeTaskVariables

What it means

taskIds(Set<String>) cannot be combined with excludeTaskVariables (excludeTaskRelated). Excluding task-related variables while filtering by a specific set of tasks is contradictory, so Flowable throws FlowableIllegalArgumentException at query-build time.

Solutions

1. Remove excludeTaskVariables() when using taskIds()
2. Split query construction into task-scoped (taskIds, no exclusion) and non-task paths
3. Handle the exclusion via post-processing of results instead

Example fix

// before
query.excludeTaskVariables().taskIds(taskIds);
// after
query.taskIds(taskIds);

if (excludeTaskRelated && taskIds != null) {
    throw new IllegalArgumentException("excludeTaskVariables cannot be combined with taskIds");
}

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

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

When it happens

Trigger: Calling variableInstanceQuery.excludeTaskVariables().taskIds(ids) in either order.

Common situations: A generic query factory that conditionally appends excludeTaskVariables for 'non-task variable' reports, accidentally applied to a task-id-based lookup.

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 excludeLocalVariables
• executionIds is null

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

Appendix: source

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

            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");
        }
        this.taskIds = taskIds;
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)