flowable/flowable-engine · error · FlowableIllegalArgumentException

variableNames are null or empty

Error message

variableNames are null or empty

What it means

Flowable throws this FlowableIllegalArgumentException when HistoricProcessInstanceQuery.includeProcessVariables(Collection<String>) is called with a null or empty collection. The query builder validates arguments eagerly so invalid queries fail at build time rather than at execution time. Only non-empty collections of variable names are accepted.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/HistoricProcessInstanceQueryImpl.java:660

        }
        if (inOrStatement) {
            this.currentOrQueryObject.involvedGroups = involvedGroups;
        } else {
            this.involvedGroups = involvedGroups;
        }
        return this;
    }

    @Override
    public HistoricProcessInstanceQuery includeProcessVariables() {
        this.includeProcessVariables = true;
        return this;
    }

    @Override
    public HistoricProcessInstanceQuery includeProcessVariables(Collection<String> variableNames) {
        if (variableNames == null || variableNames.isEmpty()) {
            throw new FlowableIllegalArgumentException("variableNames are null or empty");
        }
        includeProcessVariables();
        this.variableNamesToInclude = new LinkedHashSet<>(variableNames);
        return this;
    }

    @Override
    public HistoricProcessInstanceQuery withJobException() {
        if (inOrStatement) {
            this.currentOrQueryObject.withJobException = true;
        } else {
            this.withJobException = true;
        }
        return this;
    }

    @Override
    public HistoricProcessInstanceQuery processInstanceTenantId(String tenantId) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the collection passed to includeProcessVariables is non-null and contains at least one variable name before calling it
2. If you intend to include ALL process variables, call the no-arg includeProcessVariables() overload instead
3. Guard with a fallback: if list is empty, use the no-arg overload or skip the call

Example fix

// before
query.includeProcessVariables(variableNames);
// after
if (variableNames == null || variableNames.isEmpty()) {
    query.includeProcessVariables(); // include all
} else {
    query.includeProcessVariables(variableNames);
}

if (variableNames == null || variableNames.isEmpty()) {
    throw new IllegalArgumentException("variableNames must contain at least one name");
}

boolean isValidVariableNames(Collection<String> names) {
    return names != null && !names.isEmpty();
}

try {
    query.includeProcessVariables(variableNames);
} catch (FlowableIllegalArgumentException e) {
    query.includeProcessVariables(); // fallback: include all
}

When it happens

Trigger: Calling includeProcessVariables(null) or includeProcessVariables(Collections.emptyList()) or any variableNames.isEmpty() collection on a HistoricProcessInstanceQuery.

Common situations: Passing a variableNames list assembled dynamically from config or user input that ends up null/empty; refactoring code that previously called includeProcessVariables() (no-arg, include all) to the filtered overload.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Error retrieving app engine info
• No deployment id available
• No resource name available
• nameLike is null
• nameLikeIgnoreCase is null

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