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

Pass a non-null process definition key

flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition key is null

Error message

Process definition key is null

What it means

ExecutionQuery.processDefinitionKey() requires a non-null key; Flowable throws FlowableIllegalArgumentException because null would mean 'no filter'. Works identically inside OR statements via currentOrQueryObject.

Solutions

Pass a non-null process definition key
Conditionally apply the filter only when the key is present
Ensure the key is resolved/validated before building the query

Example fix

// before
executionQuery.processDefinitionKey(payload.getProcessKey());
// after
if (payload.getProcessKey() != null) {
    executionQuery.processDefinitionKey(payload.getProcessKey());
}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
    query.processDefinitionKey(key);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("Missing process definition key for execution query", e);
}

Prevention

Make the key a required, validated request field when the filter is mandatory
Skip the setter for optional keys instead of passing null
Keep a single query-builder utility that enforces null guards

When it happens

Trigger: Calling executionQuery.processDefinitionKey(null) with a key sourced from nullable config, message payload, or unresolved variable.

Common situations: Filtering executions for a business process whose key wasn't provided by the caller; mapping optional DTO fields unconditionally; environment-specific config missing the key.

Related errors

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:156

    }

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

    @Override
    public ExecutionQueryImpl processDefinitionKey(String processDefinitionKey) {
        if (processDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Process definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;
        } else {
            this.processDefinitionKey = processDefinitionKey;
        }
        return this;
    }
    
    @Override
    public ExecutionQueryImpl processDefinitionKeyLike(String processDefinitionKeyLike) {
        if (processDefinitionKeyLike == null) {
            throw new FlowableIllegalArgumentException("Process definition key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKeyLike = processDefinitionKeyLike;
        } else {
            this.processDefinitionKeyLike = processDefinitionKeyLike;

View on GitHub (pinned to d6d39ce1c6)