flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition version is null

Error message

Case definition version is null

What it means

Flowable throws FlowableIllegalArgumentException from CaseInstanceQueryImpl.caseDefinitionVersion(Integer) when the version argument is null. Versions are integers and an unset version must simply not be added as a criterion; null is rejected at query-build time to keep the generated SQL valid.

Solutions

1. Add the criterion only when non-null: if (version != null) query.caseDefinitionVersion(version)
2. Parse with a default: int v = parseOrDefault(raw, -1) and call caseDefinitionVersion(v) only for valid values
3. If all versions are wanted, do not call the method at all — omit it rather than passing null
4. Catch FlowableIllegalArgumentException around query building to emit a validation error

Example fix

// before
Integer version = params.get("version"); // may be null
query.caseDefinitionVersion(version);
// after
Integer version = params.get("version");
if (version != null) {
    query.caseDefinitionVersion(version);
}

if (version != null) { query.caseDefinitionVersion(version); }

boolean hasVersion = version != null && version >= 1;

try { query.caseDefinitionVersion(version); } catch (FlowableIllegalArgumentException e) { throw new BadRequestException("version must not be null"); }

When it happens

Trigger: Calling createCaseInstanceQuery().caseDefinitionVersion(null), often because the version came from an Integer variable (request param parsed to null, unset DTO field) instead of an int default.

Common situations: REST endpoints where 'version' is optional and unboxed parsing yields null; migrating code from primitive int defaults to Integer wrappers; generic filter-to-query mappers.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

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

    
    @Override
    public CaseInstanceQueryImpl caseDefinitionNameLikeIgnoreCase(String caseDefinitionNameLikeIgnoreCase) {
        if (caseDefinitionNameLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("Case definition name is null");
        }

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

    @Override
    public CaseInstanceQueryImpl caseDefinitionVersion(Integer caseDefinitionVersion) {
        if (caseDefinitionVersion == null) {
            throw new FlowableIllegalArgumentException("Case definition version is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionVersion = caseDefinitionVersion;
        } else {
            this.caseDefinitionVersion = caseDefinitionVersion;
        }
        return this;
    }

    @Override
    public CaseInstanceQueryImpl caseInstanceId(String caseInstanceId) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("Case instance id is null");
        }

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

View on GitHub (pinned to d6d39ce1c6)