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

Cannot use executionIds together with excludeLocalVariables

Error message

Cannot use executionIds together with excludeLocalVariables

What it means

HistoricVariableInstanceQueryImpl.executionIds() throws FlowableIllegalArgumentException when excludeLocalVariables(true) was already set. Execution-id filtering and local-variable exclusion are mutually exclusive for historic variable instance queries, so the builder rejects the combination at configuration time.

Solutions

1. Drop the excludeLocalVariables(true) call when filtering by execution ids
2. Apply executionIds(...) before excludeLocalVariables(true), or skip exclusion when execution ids are present
3. Construct a new query per request to avoid pre-set exclusion flags

Example fix

// before
query.excludeLocalVariables(true);
query.executionIds(ids); // throws
// after
query.executionIds(ids); // do not call excludeLocalVariables(true)

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

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

When it happens

Trigger: Calling query.executionIds(set) after query.excludeLocalVariables(true) on the same query instance.

Common situations: Query-param mapping code that always applies excludeLocalVariables before the id filters; shared query objects reused across requests with exclusion pre-enabled.

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

Appendix: source

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

            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 HistoricVariableInstanceQueryImpl 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 HistoricVariableInstanceQuery activityInstanceId(String activityInstanceId) {
        this.activityInstanceId = activityInstanceId;
        return this;
    }

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