What causes "Provided process definition key is null" in flowable/flowable-engine?

Only call processDefinitionKey(...) when the value is non-null, e.g. wrap in an if (key != null) block or Optional filter

flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided process definition key is null

Error message

Provided process definition key is null

What it means

DeadLetterJobQueryImpl.processDefinitionKey() throws FlowableIllegalArgumentException when the processDefinitionKey parameter is null. The Flowable query API validates every filter argument eagerly so that invalid queries fail at build time rather than producing broken SQL at execution time. Passing null means the caller intended to filter by process definition key but supplied no value.

Solutions

Only call processDefinitionKey(...) when the value is non-null, e.g. wrap in an if (key != null) block or Optional filter
If null should mean 'no filter', simply omit the call - the query matches all process definition keys by default
If null is invalid input, validate/reject it at the API boundary before constructing the query
Check upstream data sources (request body, config, database) for why the key is missing

Example fix

// before
DeadLetterJobQuery query = managementService.createDeadLetterJobQuery()
    .processDefinitionKey(request.getProcessDefinitionKey());

// after
DeadLetterJobQuery query = managementService.createDeadLetterJobQuery();
if (request.getProcessDefinitionKey() != null) {
    query = query.processDefinitionKey(request.getProcessDefinitionKey());
}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean hasProcessDefinitionKey(String key) { return key != null && !key.trim().isEmpty(); }

Try / catch

try {
    return jobService.createDeadLetterJobQuery().processDefinitionKey(key).list();
} catch (FlowableIllegalArgumentException e) {
    throw new InvalidQueryRequestException("processDefinitionKey must not be null", e);
}

Prevention

Build queries conditionally: only add filters whose values are present
Use Optional.ofNullable(key).filter(k -> !k.isEmpty()) to gate the setter call
Validate query DTOs at the REST boundary with Bean Validation (@NotNull when the field is required)
Never pass values straight from external input into query setters without a null check

When it happens

Trigger: Calling deadLetterJobQuery().processDefinitionKey(null) directly, or indirectly via helper/wrapper code that forwards a possibly-null variable (e.g. processDefinitionKey from a request parameter) into the query builder.

Common situations: Building queries from REST request DTOs where the processDefinitionKey field is optional and not null-checked; dynamic query builders that conditionally add filters but accidentally call the setter with a null; refactors where a default key constant was removed.

Related errors

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

Appendix: source

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

    }

    @Override
    public DeadLetterJobQueryImpl processDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new FlowableIllegalArgumentException("Provided process definition id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionId = processDefinitionId;
        } else {
            this.processDefinitionId = processDefinitionId;
        }
        return this;
    }

    @Override
    public DeadLetterJobQueryImpl processDefinitionKey(String processDefinitionKey) {
        if (processDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Provided process definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;
        } else {
            this.processDefinitionKey = processDefinitionKey;
        }
        return this;
    }
    
    @Override
    public DeadLetterJobQueryImpl category(String category) {
        if (category == null) {
            throw new FlowableIllegalArgumentException("Provided category is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.category = category;
        } else {
            this.category = category;

View on GitHub (pinned to d6d39ce1c6)