flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process definition name is null

Error message

Process definition name is null

What it means

ProcessInstanceQueryImpl.processDefinitionName(String) throws ActivitiIllegalArgumentException when the processDefinitionName argument is null. The query API treats null as an invalid filter value and rejects it eagerly so the failure surfaces at query construction rather than during SQL execution. To leave the filter unset, simply do not call the method.

Source

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

    @Override
    public ProcessInstanceQuery processDefinitionCategory(String processDefinitionCategory) {
        if (processDefinitionCategory == null) {
            throw new ActivitiIllegalArgumentException("Process definition category is null");
        }

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

    @Override
    public ProcessInstanceQuery processDefinitionName(String processDefinitionName) {
        if (processDefinitionName == null) {
            throw new ActivitiIllegalArgumentException("Process definition name is null");
        }

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

    @Override
    public ProcessInstanceQuery processDefinitionVersion(Integer processDefinitionVersion) {
        if (processDefinitionVersion == null) {
            throw new ActivitiIllegalArgumentException("Process definition version is null");
        }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Apply the filter conditionally: only call processDefinitionName when the value is non-null.
2. Coalesce blank/absent input to 'no filter' rather than null.
3. Validate incoming DTOs (e.g. @NotNull or manual checks) before mapping them into query calls.
4. Catch ActivitiIllegalArgumentException and convert it into a client-facing validation message.

Example fix

// before
query.processDefinitionName(filter.getName());
// after
if (filter.getName() != null) {
    query = query.processDefinitionName(filter.getName());
}

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

boolean hasDefinitionName(String name) { return name != null && !name.isEmpty(); }

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

When it happens

Trigger: Calling .processDefinitionName(null) — typically the name comes from an unvalidated request parameter, a UI filter that was left blank, or a lookup that returned null.

Common situations: Search screens that forward all filter fields regardless of whether the user filled them; deserialized filter DTOs with null fields applied blindly; renaming a form field so the old lookup returns null.

Related errors

• process instance tenant id is null
• Process definition category is null
• Process definition version is null
• Process definition id is null
• Set of process definition ids is null

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