flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition name is null

Error message

Process definition name is null

What it means

ProcessInstanceQuery.processDefinitionName(String) validates its argument before storing it as a query filter. If the argument is null, the query would be semantically undefined (a null filter on the PROC_DEF_NAME_ column), so Flowable throws FlowableIllegalArgumentException early with 'Process definition name is null' instead of producing a broken SQL query. This is fail-fast input validation at query-building time, not an execution-time failure.

Source

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

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

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

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

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionName = processDefinitionName;
        } else {
            this.processDefinitionName = processDefinitionName;
        }
        return this;
    }
    
    @Override
    public ProcessInstanceQuery processDefinitionNameLike(String processDefinitionNameLike) {
        if (processDefinitionNameLike == null) {
            throw new FlowableIllegalArgumentException("Process definition name is null");
        }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check the argument with a null test before calling processDefinitionName and skip or branch the filter when it is null
2. Trace where the name comes from (config, request param, repository lookup) and fix the producer so it returns a real value or a sensible default
3. If a null filter should mean 'no filtering', omit the call entirely rather than passing null
4. Wrap the query building in try/catch for FlowableIllegalArgumentException to surface a clear message to the caller

Example fix

// before
String name = repositoryService.createProcessDefinitionQuery().singleResult().getName();
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery().processDefinitionName(name); // NPE/null risk upstream, name may be null

// after
String name = repositoryService.createProcessDefinitionQuery().singleResult().getName();
ProcessInstanceQuery q = runtimeService.createProcessInstanceQuery();
if (name != null) {
    q = q.processDefinitionName(name);
}

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

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

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

When it happens

Trigger: Calling runtimeService.createProcessInstanceQuery().processDefinitionName(null) — either directly with a literal null or with a String variable that is null at call time.

Common situations: A process definition name read from configuration, a REST request parameter, or an upstream lookup is null because the definition was not found, the property is missing, or an earlier API returned null; developers also hit it when conditionally building queries and passing through unset variables without a null check.

Related errors

• Set of process instance ids is null
• rootScopeIds is null or empty
• parentScopeIds is null or empty
• userId is null
• identityLinkType is null

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