flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process definition key is null

Error message

Process definition key is null

What it means

ProcessInstanceQueryImpl.processDefinitionKey(String) throws ActivitiIllegalArgumentException when the processDefinitionKey argument is null. The key (the BPMN process id) must be a concrete non-null value; null is treated as an invalid filter and rejected at query build time. To filter by a prefix use processDefinitionKeyLike, or omit the call for no filtering.

Solutions

1. Null-check the key before calling; skip the filter or fail with your own message if absent.
2. Prefer conditional query building so unset filters are simply not applied.
3. Validate request parameters with @NotNull/@NotBlank or manual checks before query construction.
4. Catch ActivitiIllegalArgumentException around query building and surface a named-parameter validation error.

Example fix

// before
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery()
    .processDefinitionKey(param);
// after
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery();
if (param != null) {
    q = q.processDefinitionKey(param);
}

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

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

try {
    result = query.processDefinitionKey(key).list();
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("Process definition key is null")) {
        throw new BadRequestException("processDefinitionKey must not be null");
    }
    throw e;
}

When it happens

Trigger: Calling .processDefinitionKey(null) — usually a key read from a request parameter, BPMN config, or lookup map that is missing/null.

Common situations: REST controllers passing unvalidated path/query params; process key resolved from an external config that changed names; Optional.map chains returning null when the source was empty.

Related errors

• Process definition category is null
• Process definition id is null
• Process definition name is null
• Process definition version is null
• process instance tenant id is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:265

        if (processDefinitionIds == null) {
            throw new ActivitiIllegalArgumentException("Set of process definition ids is null");
        }
        if (processDefinitionIds.isEmpty()) {
            throw new ActivitiIllegalArgumentException("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 ActivitiIllegalArgumentException("Process definition key is null");
        }

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

    @Override
    public ProcessInstanceQuery processDefinitionKeys(Set<String> processDefinitionKeys) {
        if (processDefinitionKeys == null) {
            throw new ActivitiIllegalArgumentException("Set of process definition keys is null");
        }
        if (processDefinitionKeys.isEmpty()) {
            throw new ActivitiIllegalArgumentException("Set of process definition keys is empty");
        }

View on GitHub (pinned to d6d39ce1c6)