flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition key is null

Error message

Process definition key is null

What it means

ProcessInstanceQueryImpl.processDefinitionKey(String) throws FlowableIllegalArgumentException('Process definition key is null') when the key argument is null. The key is the business identifier of a process definition and is used as an exact-match filter; a null cannot form a valid condition, so it is rejected during query building before being stored on the query or its OR-query object.

Solutions

1. Null-check the key before calling processDefinitionKey and skip the filter or reject the request when null
2. Validate/default the key at the input boundary (REST handler, config loader) before it reaches query building
3. Use processDefinitionId or processDefinitionName if that is what your data actually provides
4. Catch FlowableIllegalArgumentException and return a clear validation error to the caller

Example fix

// before
String key = properties.getProperty("process.key");
query.processDefinitionKey(key); // throws when property missing

// after
String key = properties.getProperty("process.key");
if (key != null) {
    query.processDefinitionKey(key);
} else {
    throw new IllegalStateException("process.key must be configured");
}

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

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

try {
    query.processDefinitionKey(key);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("processDefinitionKey must not be null", e);
}

When it happens

Trigger: Calling .processDefinitionKey(null), usually when the key comes from a nullable config value, an omitted request parameter, or a variable extracted from an object whose key field is unset.

Common situations: Workflow launch consoles where the process key is chosen from a dropdown and no default is set; deployment scripts where the key property was renamed; API consumers omitting the key and the server passing the value straight through.

Related errors

• executionIds is null
• groupId is null
• identityLinkType is null
• involvedGroups are null
• parentScopeIds is null or empty

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:437

        if (processDefinitionIds == null) {
            throw new FlowableIllegalArgumentException("Set of process definition ids is null");
        }
        if (processDefinitionIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of process definition ids is empty");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionIds = processDefinitionIds;
        } else {
            this.processDefinitionIds = processDefinitionIds;
        }
        return this;
    }

    @Override
    public ProcessInstanceQueryImpl 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 ProcessInstanceQueryImpl processDefinitionKeyLike(String processDefinitionKeyLike) {
        if (processDefinitionKeyLike == null) {
            throw new FlowableIllegalArgumentException("Process definition key is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKeyLike = processDefinitionKeyLike;

View on GitHub (pinned to d6d39ce1c6)