flowable/flowable-engine · error · FlowableIllegalArgumentException

Case definition id is null

Error message

Case definition id is null

What it means

Flowable's PlanItemInstanceQuery.caseDefinitionId() throws FlowableIllegalArgumentException when caseDefinitionId is null. Query setters validate arguments eagerly so bad queries fail at construction rather than deep inside the query executor. A case-definition filter requires a concrete id string.

Solutions

1. Pass a valid case definition id (e.g. from CmmnRepositoryService.createCaseDefinitionQuery() results)
2. Skip the caseDefinitionId filter when the id is null rather than passing null
3. Verify the case definition is deployed and its id is resolved before querying

Example fix

// before
query.caseDefinitionId(caseDefinitionId); // throws when null

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

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

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

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

When it happens

Trigger: Calling planItemInstanceQuery.caseDefinitionId(null), typically when the case definition id variable comes from an unresolved lookup, a REST path variable, or process context that was never populated.

Common situations: Dashboard/report code building queries from optional request parameters; a case definition deployed under a different key so the lookup for its id returns null; tests where deployment setup was skipped.

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

Appendix: source

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

    public PlanItemInstanceQueryImpl() {
        
    }
    
    public PlanItemInstanceQueryImpl(CommandContext commandContext, CmmnEngineConfiguration cmmnEngineConfiguration) {
        super(commandContext, cmmnEngineConfiguration.getVariableServiceConfiguration());
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

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

    @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;

View on GitHub (pinned to d6d39ce1c6)