flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition id is null

Error message

Case definition id is null

What it means

CaseInstanceQueryImpl.caseDefinitionId validates its argument before storing it on the query object. Passing null throws FlowableIllegalArgumentException because a null caseDefinitionId filter is ambiguous with 'no filter'; callers must simply not call the method instead of passing null.

Solutions

1. Pass a non-null case definition id string.
2. Skip calling caseDefinitionId when the value is null (build the query conditionally).
3. At the API boundary, coerce empty/absent values to 'do not filter' rather than null.

Example fix

// before
query.caseDefinitionId(request.getDefinitionId()).list();
// after
if (request.getDefinitionId() != null) {
    query = query.caseDefinitionId(request.getDefinitionId());
}
query.list();

if (caseDefinitionId != null) {
    query = query.caseDefinitionId(caseDefinitionId);
}

When it happens

Trigger: cmmnRuntimeService.createCaseInstanceQuery().caseDefinitionId(null).list() — directly or via a variable holding the id that is null.

Common situations: Wiring a search/filter form where the definition-id field is optional and the raw value is forwarded without a null check; mapping query params to query criteria generically.

Related errors

• Case definition category is null
• Case definition key is null
• activatedBefore is null
• assignee is null
• availableAfter is null

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

Appendix: source

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

    public CaseInstanceQueryImpl(CommandExecutor commandExecutor, CmmnEngineConfiguration cmmnEngineConfiguration) {
        super(commandExecutor, cmmnEngineConfiguration.getVariableServiceConfiguration());
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

    @Override
    protected void ensureVariablesInitialized() {
        super.ensureVariablesInitialized();

        for (CaseInstanceQueryImpl orQueryObject : orQueryObjects) {
            orQueryObject.ensureVariablesInitialized();
        }
    }

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

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

    @Override
    public CaseInstanceQueryImpl caseDefinitionIds(Set<String> caseDefinitionIds) {
        if (caseDefinitionIds == null) {
            throw new FlowableIllegalArgumentException("Case definition ids is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionIds = caseDefinitionIds;

View on GitHub (pinned to d6d39ce1c6)