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

Cannot use taskIds together with excludeTaskVariables

Error message

Cannot use taskIds together with excludeTaskVariables

What it means

HistoricVariableInstanceQueryImpl.taskIds() throws FlowableIllegalArgumentException when excludeTaskVariables (excludeTaskRelated) has already been enabled. Filtering by a set of task ids while excluding task-related variables is contradictory and rejected at query-configuration time.

Solutions

1. Remove excludeTaskVariables() when filtering by task ids
2. Apply taskIds(...) before enabling exclusion, or skip exclusion when task ids are present
3. Instantiate a fresh query per request to avoid pre-enabled exclusion flags

Example fix

// before
query.excludeTaskVariables();
query.taskIds(taskIds); // throws
// after
query.taskIds(taskIds); // do not call excludeTaskVariables()

boolean excludeTaskRelated = /* your exclude flag */;
if (excludeTaskRelated && taskIds != null && !taskIds.isEmpty()) {
    throw new IllegalStateException("taskIds and excludeTaskVariables are mutually exclusive");
}

try {
    query.taskIds(taskIds);
} catch (FlowableIllegalArgumentException e) {
    // handle conflicting query options
}

When it happens

Trigger: Calling query.taskIds(set) after query.excludeTaskVariables()/excludeTaskRelated(true) on the same query instance.

Common situations: Request-driven builder code that applies the exclusion flag from one query param and task-id filters from another; reused query objects.

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

Appendix: source

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

            throw new FlowableIllegalArgumentException("Cannot use taskId together with excludeTaskVariables");
        }
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use taskId together with excludeLocalVariables");
        }
        this.taskId = taskId;
        return this;
    }

    @Override
    public HistoricVariableInstanceQueryImpl 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 HistoricVariableInstanceQuery 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)