flowable/flowable-engine · error · FlowableIllegalArgumentException

variableNames is null or empty

Error message

variableNames is null or empty

What it means

HistoricCaseInstanceQueryImpl.includeCaseVariables(Collection<String>) throws FlowableIllegalArgumentException when the passed collection of variable names is null or empty. The query API requires an explicit, non-empty list of variable names to include in the result, because 'include variables' without a list is meaningless and would produce an invalid query.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:1046

    public String deleteInParallelUsingBatch(int batchSize, String batchName) {
        return commandExecutor.execute(new DeleteHistoricCaseInstancesUsingBatchesCmd(this, batchSize, batchName, false));
    }

    @Override
    public String deleteSequentiallyUsingBatch(int batchSize, String batchName) {
        return commandExecutor.execute(new DeleteHistoricCaseInstancesUsingBatchesCmd(this, batchSize, batchName, true));
    }

    @Override
    public HistoricCaseInstanceQuery includeCaseVariables() {
        this.includeCaseVariables = true;
        return this;
    }

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

    @Override
    public HistoricCaseInstanceQuery activePlanItemDefinitionId(String planItemDefinitionId) {
        if (planItemDefinitionId == null) {
            throw new FlowableIllegalArgumentException("planItemDefinitionId is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.activePlanItemDefinitionId = planItemDefinitionId;
        } else {
            this.activePlanItemDefinitionId = planItemDefinitionId;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the collection passed to includeCaseVariables is non-null and contains at least one variable name before calling it.
2. If you want ALL case variables included, call the no-arg includeCaseVariables() instead of the collection overload.
3. Skip calling includeCaseVariables(collection) when the list is empty, and execute the query without variable inclusion.
4. Add a guard that logs/normalizes empty lists before constructing the query.

Example fix

// before
query.includeCaseVariables(variableNames); // variableNames may be null/empty
// after
if (variableNames != null && !variableNames.isEmpty()) {
    query.includeCaseVariables(variableNames);
}

if (variableNames == null || variableNames.isEmpty()) {
    throw new IllegalArgumentException("variableNames must be non-empty");
}
query.includeCaseVariables(variableNames);

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

try {
    query.includeCaseVariables(variableNames);
} catch (FlowableIllegalArgumentException e) {
    if ("variableNames is null or empty".equals(e.getMessage())) {
        // fall back to query without included variables or rethrow with context
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling includeCaseVariables(null) or includeCaseVariables(Collections.emptyList()) on a HistoricCaseInstanceQuery (or via the CMMN runtime/history service fluent query API) before executing the query.

Common situations: Building the variable-name list dynamically from user input or config where the collection ends up null/empty; upgrading Flowable versions where includeCaseVariables() previously called with no args was separated from the collection overload; copying code from case-variable queries and forgetting to populate the list.

Related errors

• planItemDefinitionId is null
• planItemDefinitionIds is null
• involvedUser is null
• userId is null
• identityLinkType is null

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