flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition version is null

Error message

Case definition version is null

What it means

caseDefinitionVersion(Integer) rejects a null version argument with FlowableIllegalArgumentException. The query implementation stores the version for SQL filtering and cannot represent 'unset' as null once the setter is invoked.

Source

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

    }
    
    @Override
    public HistoricCaseInstanceQueryImpl 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 HistoricCaseInstanceQueryImpl 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 HistoricCaseInstanceQueryImpl caseInstanceId(String caseInstanceId) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("Case instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseInstanceId = caseInstanceId;
        } else {
            this.caseInstanceId = caseInstanceId;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a valid version integer (e.g. 1).
2. Only invoke the setter when the Integer is non-null.
3. Catch FlowableIllegalArgumentException to convert it into a client-facing validation error.

Example fix

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

if (caseDefinitionVersion == null) { throw new IllegalArgumentException("caseDefinitionVersion must not be null"); }
historicCaseInstanceQuery.caseDefinitionVersion(caseDefinitionVersion);

boolean isValidVersion(Integer v) { return v != null && v > 0; }

try {
    query.caseDefinitionVersion(version);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("Invalid case definition version", e);
}

When it happens

Trigger: Calling caseDefinitionVersion(null) directly, or passing an Integer variable that was never initialized or failed to parse from a string.

Common situations: Parsing request parameters with Integer.valueOf on missing/empty input; mapping JSON bodies where the version field is optional.

Related errors

• Case instance id is null
• Case instance ids is null
• Business key is null
• rootScopeId is null
• rootScopeIds is null or empty

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