flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided case definition key is null

Error message

Provided case definition key is null

What it means

This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.caseDefinitionKey() when the caller passes a null definition key. The key is the business identifier of a case definition and must be non-null for a valid filter. As with all Flowable query setters, validation happens immediately during query construction, not at list()/count() time.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java:347

        scopeId(caseInstanceId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl caseDefinitionId(String caseDefinitionId) {
        if (caseDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Provided case definition id is null");
        }
        scopeDefinitionId(caseDefinitionId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }

    @Override
    public SuspendedJobQueryImpl caseDefinitionKey(String caseDefinitionKey) {
        if (caseDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Provided case definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionKey = caseDefinitionKey;
        } else {
            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl planItemInstanceId(String planItemInstanceId) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("Provided plan item instance id is null");
        }
        subScopeId(planItemInstanceId);
        scopeType(ScopeTypes.CMMN);
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Guard the call: only apply caseDefinitionKey() when non-null
2. Resolve the key from configuration with a validated default or fail earlier with a clearer message
3. Use caseDefinitionId() when you actually hold an id rather than a key
4. Validate required inputs at the entry point of your service

Example fix

// before
query.caseDefinitionKey(definitionKey); // may be null
// after
if (definitionKey != null) {
    query.caseDefinitionKey(definitionKey);
}

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

boolean hasCaseDefinitionKey = caseDefinitionKey != null && !caseDefinitionKey.isBlank();

try {
    query.caseDefinitionKey(caseDefinitionKey);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("case definition key is null")) {
        // rebuild query without key filter or raise a config error
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling suspendedJobQuery().caseDefinitionKey(null), usually when the key came from an unset configuration property, a missing request parameter, or a lookup that returned null.

Common situations: Properties/YAML configuration with a missing key value; REST clients omitting the key; version upgrades where the key source changed from required to optional.

Related errors

• Provided scope id is null
• Provided sub scope id is null
• Provided case instance id is null
• Provided case definition id is null
• Deployment id is null

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