flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided process definition key is null

Error message

Provided process definition key is null

What it means

ExternalWorkerJobQuery.processDefinitionKey(String) throws FlowableIllegalArgumentException when the provided process definition key is null. Like the other query filters, Flowable rejects null eagerly so callers cannot accidentally build an invalid query. Provide the BPMN key of the process definition or omit the filter.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java:162

    }

    @Override
    public ExternalWorkerJobQuery 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 ExternalWorkerJobQuery 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 ExternalWorkerJobQuery 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)

Solutions

1. Pass the actual process definition key from the BPMN model's process id.
2. Guard the call site with a null/blank check before adding the filter.
3. If the key is dynamic, substitute a resolved default key.
4. Validate request/config inputs before mapping them into query filters.

Example fix

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

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

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

try {
    query.processDefinitionKey(key);
} catch (FlowableIllegalArgumentException e) {
    // proceed without the key filter or fail fast with a clear message
}

When it happens

Trigger: Calling externalWorkerJobQuery().processDefinitionKey(null), e.g. when the key comes from a form field, BPMN model attribute, or property file that is empty/null.

Common situations: Generic admin tools that build queries from request parameters where 'processDefinitionKey' is optional; BPMN models with a missing or renamed key attribute; Spring configuration properties not set.

Related errors

• category is null
• name is null
• Provided process definition id is null
• categoryLike is null
• categoryNotEquals is null

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