flowable/flowable-engine · error · FlowableIllegalArgumentException

planItemDefinitionId is null

Error message

planItemDefinitionId is null

What it means

FlowableIllegalArgumentException thrown by CaseInstanceQueryImpl.activePlanItemDefinitionId(String) when planItemDefinitionId is null. This filter restricts case instances that currently have an active plan item of the given definition id; null is not a valid definition reference. Pass a real plan item definition id from the case model.

Solutions

1. Pass a non-null planItemDefinitionId string.
2. Skip the filter when no plan item restriction is intended.
3. Resolve the definition id from the case model/repository service and check for null before querying.
4. Use the activePlanItemDefinitionId variant (like/ignore-case) appropriate to your data instead of a null.

Example fix

// before
query.activePlanItemDefinitionId(config.getPlanItemDefId()); // may be null
// after
String defId = config.getPlanItemDefId();
if (defId != null) {
    query.activePlanItemDefinitionId(defId);
}

if (planItemDefinitionId != null) { query.activePlanItemDefinitionId(planItemDefinitionId); }

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

try { query.activePlanItemDefinitionId(defId); } catch (FlowableIllegalArgumentException e) { log.warn("planItemDefinitionId null: {}", e.getMessage()); }

When it happens

Trigger: Calling activePlanItemDefinitionId(null) on a CaseInstanceQuery, e.g. when the plan item definition id came from configuration or a lookup that returned null.

Common situations: Dashboards showing cases stuck on a specific stage/user event listener where the definition id was not resolved from the CMMN model; wrong key used to fetch the definition.

Related errors

• Business key is null
• Business status is null
• callbackIds is null or empty
• callbackType is null
• Case definition keys is null

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

Appendix: source

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

        }
        return this;
    }
    
    @Override
    public CaseInstanceQueryImpl caseInstanceWithoutTenantId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutTenantId = true;
        } else {
            this.withoutTenantId = true;
        }

        return this;
    }
    
    @Override
    public CaseInstanceQuery activePlanItemDefinitionId(String planItemDefinitionId) {
        if (planItemDefinitionId == null) {
            throw new FlowableIllegalArgumentException("planItemDefinitionId is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.activePlanItemDefinitionId = planItemDefinitionId;
        } else {
            this.activePlanItemDefinitionId = planItemDefinitionId;
        }
        return this;
    }
    
    @Override
    public CaseInstanceQuery activePlanItemDefinitionIds(Set<String> planItemDefinitionIds) {
        if (planItemDefinitionIds == null) {
            throw new FlowableIllegalArgumentException("planItemDefinitionIds is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.activePlanItemDefinitionIds = planItemDefinitionIds;
        } else {
            this.activePlanItemDefinitionIds = planItemDefinitionIds;

View on GitHub (pinned to d6d39ce1c6)