flowable/flowable-engine · error · FlowableIllegalArgumentException

variableNames is null or empty

Error message

variableNames is null or empty

What it means

CaseInstanceQueryImpl.includeCaseVariables(Collection<String>) validates its input before enabling variable inclusion on the query. If the collection is null or empty, the query would be semantically identical to no inclusion, so Flowable throws FlowableIllegalArgumentException to surface the misuse immediately.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceQueryImpl.java:1068

        return this;
    }

    @Override
    public CaseInstanceQueryImpl orderByTenantId() {
        this.orderProperty = CaseInstanceQueryProperty.TENANT_ID;
        return this;
    }

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

    @Override
    public CaseInstanceQuery 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 CaseInstanceQuery locale(String locale) {
        this.locale = locale;
        return this;
    }

    @Override
    public CaseInstanceQuery withLocalizationFallback() {
        this.withLocalizationFallback = true;
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the variable-name collection is populated before calling includeCaseVariables; fall back to includeCaseVariables() (no-arg) when you want all variables
2. Guard with a null/empty check and skip the call or use the no-arg variant
3. Fix the upstream source of the collection so it is not null/empty

Example fix

// before
query.includeCaseVariables(variableNames); // NPE/IAE when variableNames is null/empty
// after
if (variableNames == null || variableNames.isEmpty()) {
    query.includeCaseVariables(); // include all variables
} else {
    query.includeCaseVariables(variableNames);
}

if (variableNames == null || variableNames.isEmpty()) { query.includeCaseVariables(); } else { query.includeCaseVariables(variableNames); }

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

try { query.includeCaseVariables(variableNames); } catch (FlowableIllegalArgumentException e) { query.includeCaseVariables(); }

When it happens

Trigger: Calling cmmnRuntimeService.createCaseInstanceQuery().includeCaseVariables(null) or includeCaseVariables(Collections.emptyList()) / an empty set or list.

Common situations: Passing a variable-name list that was built dynamically (e.g., from user selection or config) and turned out empty; passing null because a caller variable was never initialized; refactoring code that previously called includeCaseVariables() (no-arg) and incorrectly switched to the collection variant.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• query is null
• parentScopeIds is null or empty
• Business status is null
• Case definition keys is null
• tenant id is null

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