flowable/flowable-engine · error · ActivitiIllegalArgumentException

key is null

Error message

key is null

What it means

ProcessDefinitionQueryImpl.processDefinitionKey(String) throws ActivitiIllegalArgumentException 'key is null' when the key argument is null. The process definition key (the bpmn 'process id') is a mandatory non-null filter value, validated eagerly when the query is built. Passing null violates the API contract.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessDefinitionQueryImpl.java:159

            throw new ActivitiIllegalArgumentException("id is null");
        }
        this.deploymentId = deploymentId;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl deploymentIds(Set<String> deploymentIds) {
        if (deploymentIds == null) {
            throw new ActivitiIllegalArgumentException("ids are null");
        }
        this.deploymentIds = deploymentIds;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionKey(String key) {
        if (key == null) {
            throw new ActivitiIllegalArgumentException("key is null");
        }
        this.key = key;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionKeyLike(String keyLike) {
        if (keyLike == null) {
            throw new ActivitiIllegalArgumentException("keyLike is null");
        }
        this.keyLike = keyLike;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionResourceName(String resourceName) {
        if (resourceName == null) {
            throw new ActivitiIllegalArgumentException("resourceName is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass the actual process definition key (the id attribute of the process in the BPMN XML)
  2. Guard the call: only apply the key filter when the value is non-null
  3. Fail earlier with a domain-specific error if the key is required input
  4. Catch ActivitiIllegalArgumentException and return a meaningful validation message

Example fix

// before
query.processDefinitionKey(variables.get("processKey")); // may be null
// after
String key = (String) variables.get("processKey");
if (key != null) {
    query.processDefinitionKey(key);
}
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

When it happens

Trigger: Calling ProcessDefinitionQuery.processDefinitionKey(null), commonly when the key originates from a request parameter, workflow variable, or lookup that returned null.

Common situations: Camel/Spring integration passing an unset header as the key; service-layer methods with optional key parameters forwarded straight into the query; typo'd property names leaving the key null in configuration.

Related errors

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