flowable/flowable-engine · error · FlowableIllegalArgumentException

Case instance id is null

Error message

Case instance id is null

What it means

caseInstanceId(String) throws FlowableIllegalArgumentException when given null. A null case-instance id cannot be used as a query filter, so the engine fails fast at the setter instead of producing invalid SQL.

Source

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

    }

    @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;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceIds(Set<String> caseInstanceIds) {
        if (caseInstanceIds == null) {
            throw new FlowableIllegalArgumentException("Case instance ids is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseInstanceIds = caseInstanceIds;
        } else {
            this.caseInstanceIds = caseInstanceIds;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a valid case instance id string.
2. Guard the call with a null check when the id is optional.
3. Catch FlowableIllegalArgumentException and surface a validation message.

Example fix

// before
query.caseInstanceId(variables.get("caseInstanceId"));
// after
String id = variables.get("caseInstanceId");
if (id != null) {
    query.caseInstanceId(id);
}

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

boolean hasId(String id) { return id != null && !id.isEmpty(); }

try {
    query.caseInstanceId(caseInstanceId);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("caseInstanceId is required", e);
}

When it happens

Trigger: Calling caseInstanceId(null) when the id variable came from an unpopulated variable, an optional path parameter, or a failed lookup.

Common situations: REST handlers passing path variables that are absent; chaining queries where a prior result returned no id.

Related errors

• Case definition version 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/e1b75df9862875e2. Report an issue: GitHub.