flowable/flowable-engine · error · FlowableIllegalArgumentException

Derived case definition id is null

Error message

Derived case definition id is null

What it means

Flowable's PlanItemInstanceQuery.derivedCaseDefinitionId() throws FlowableIllegalArgumentException when derivedCaseDefinitionId is null. Derived case definitions are dynamically instantiated variants of a case definition; filtering by one requires a non-null id. The check happens immediately in the setter, before query execution.

Solutions

1. Pass the actual derived case definition id (resolve it from the case instance or runtime service before querying)
2. Make the filter conditional: only call derivedCaseDefinitionId when the id is non-null
3. If you meant the static definition, use caseDefinitionId(...) with a resolved id instead

Example fix

// before
query.derivedCaseDefinitionId(derivedId); // throws when derivedId == null

// after
if (derivedId != null) {
    query.derivedCaseDefinitionId(derivedId);
}

if (derivedCaseDefinitionId != null && !derivedCaseDefinitionId.isBlank()) {
    query.derivedCaseDefinitionId(derivedCaseDefinitionId);
}

boolean isPresent(String id) { return id != null && !id.isBlank(); }

try {
    query.derivedCaseDefinitionId(derivedCaseDefinitionId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Derived case definition filter skipped: {}", e.getMessage());
}

When it happens

Trigger: Calling derivedCaseDefinitionId(null), usually because the derived-definition id was taken from a variable, form field, or API payload that was empty or absent.

Common situations: Applications using CMMN dynamic case variants where the derived definition hasn't been created/resolved yet; clients omitting the parameter in REST calls; copying code from caseDefinitionId into derivedCaseDefinitionId without wiring the new source.

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/f2b2f3fe40e027d6. Report an issue: GitHub.

Appendix: source

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

    }

    @Override
    public PlanItemInstanceQuery 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 PlanItemInstanceQuery derivedCaseDefinitionId(String derivedCaseDefinitionId) {
        if (derivedCaseDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Derived case definition id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.derivedCaseDefinitionId = derivedCaseDefinitionId;
        } else {
            this.derivedCaseDefinitionId = derivedCaseDefinitionId;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery 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)