flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided case definition key null

Error message

Provided case definition key null

What it means

DeadLetterJobQueryImpl.caseDefinitionKey() throws FlowableIllegalArgumentException when the caseDefinitionKey parameter is null. The key is the business identifier of a case definition, and a null key would produce an invalid filter, so Flowable rejects it at query-build time. This is a client-side precondition check, not a runtime failure.

Solutions

1. Null-check (and optionally blank-check) the key before passing it to caseDefinitionKey.
2. Load the key from a validated configuration source and fail with a clear message if missing at startup.
3. If filtering by key is optional, add the condition only when the key is present.

Example fix

// before
query.caseDefinitionKey(config.getCaseKey());
// after
String key = config.getCaseKey();
if (key != null && !key.isBlank()) {
    query.caseDefinitionKey(key);
}

if (caseDefinitionKey == null || caseDefinitionKey.isBlank()) { throw new IllegalArgumentException("caseDefinitionKey is required"); }
query.caseDefinitionKey(caseDefinitionKey);

boolean hasKey(String key) { return key != null && !key.isBlank(); }

try { query.caseDefinitionKey(key); } catch (FlowableIllegalArgumentException e) { log.warn("Null case definition key supplied"); }

When it happens

Trigger: Calling deadLetterJobQuery().caseDefinitionKey(null) with a key sourced from configuration, a request parameter, or a variable that was never populated, including within or() blocks.

Common situations: Missing application property for the case key; API caller omitted the key; key renamed across deployments so old lookups now resolve to null.

Related errors

• parentScopeId is null
• parentScopeIds is null or empty
• Process instance id is null
• Provided element ids are null
• Provided element name is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java:344

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

    @Override
    public DeadLetterJobQueryImpl caseDefinitionKey(String caseDefinitionKey) {
        if (caseDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Provided case definition key null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseDefinitionKey = caseDefinitionKey;
        } else {
            this.caseDefinitionKey = caseDefinitionKey;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQuery 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)