Activiti/Activiti · error · ActivitiIllegalArgumentException

Process definition key is null

Error message

Process definition key is null

What it means

ProcessInstanceQueryImpl.processDefinitionKey() throws ActivitiIllegalArgumentException when the key string is null. The key is a required, validated filter value used to match process definitions by their identifier.

Solutions

1. Null-check the key and only add the filter when present
2. Validate/sanitize inputs before building the query
3. Omit the call when null should mean 'any process definition'

Example fix

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

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

boolean hasKey(String k) { return k != null && !k.trim().isEmpty(); }

try {
    query.processDefinitionKey(key);
} catch (ActivitiIllegalArgumentException e) {
    logger.warn("Missing process key: {}", e.getMessage());
}

When it happens

Trigger: Calling .processDefinitionKey(null), usually when the key comes from an optional config entry, path variable, or lookup that returned null.

Common situations: REST endpoints where the key query param is absent; properties files missing the key; renaming process definitions and stale references returning null.

Related errors

• Involved user is null
• key is null
• name is null
• Process definition id is null
• Process definition version is null

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/394fa92b3ef2af4f. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:267

    public ProcessInstanceQuery processDefinitionIds(Set<String> processDefinitionIds) {
        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;
    }

    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 56435b1a97)