flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition name is null

Error message

Process definition name is null

What it means

FlowableIllegalArgumentException thrown by ExecutionQueryImpl.processDefinitionName when the name argument is null. Flowable requires query filters to be omitted rather than set to null, so it throws immediately during query building. This prevents invalid criteria from reaching the SQL layer.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:234

    }
    
    @Override
    public ExecutionQuery 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 ExecutionQuery 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 ExecutionQuery processDefinitionNameLike(String processDefinitionNameLike) {
        if (processDefinitionNameLike == null) {
            throw new FlowableIllegalArgumentException("Process definition name is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionNameLike = processDefinitionNameLike;
        } else {
            this.processDefinitionNameLike = processDefinitionNameLike;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Apply the filter only if the name is non-null.
2. Default the name at the source (config, DTO, or service layer).
3. Use processDefinitionNameLike for partial matching.
4. Omit the name filter to match all definitions.

Example fix

// before
query.processDefinitionName(request.getName());

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

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

boolean hasName = name != null && !name.isEmpty();

try {
    query.processDefinitionName(name);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null process definition name filter skipped");
}

When it happens

Trigger: Calling runtimeService.createExecutionQuery().processDefinitionName(null), or in an or-statement setting a null name on currentOrQueryObject.

Common situations: Process name pulled from deployment metadata or user selection that is missing; bean properties that default to null.

Related errors

• Process definition category is null
• appsDefinitionIds is null
• category is null
• query is null
• parentScopeIds is null or empty

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