flowable/flowable-engine · error · FlowableIllegalArgumentException

name is null

Error message

name is null

What it means

ProcessDefinitionQueryImpl.processDefinitionName() filters definitions by their exact name, which must be a non-null String. Passing null would create an invalid equality filter, so the query throws FlowableIllegalArgumentException as soon as the setter is called. The name here refers to the process definition name from the BPMN model, not the key.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessDefinitionQueryImpl.java:130

            throw new FlowableIllegalArgumentException("categoryLike is null");
        }
        this.categoryLike = categoryLike;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionCategoryNotEquals(String categoryNotEquals) {
        if (categoryNotEquals == null) {
            throw new FlowableIllegalArgumentException("categoryNotEquals is null");
        }
        this.categoryNotEquals = categoryNotEquals;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionName(String name) {
        if (name == null) {
            throw new FlowableIllegalArgumentException("name is null");
        }
        this.name = name;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionNameLike(String nameLike) {
        if (nameLike == null) {
            throw new FlowableIllegalArgumentException("nameLike is null");
        }
        this.nameLike = nameLike;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionNameLikeIgnoreCase(String nameLikeIgnoreCase) {
        if (nameLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("nameLikeIgnoreCase is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the name before building the query and return a clear client error if missing.
2. Guard: if (name != null) query.processDefinitionName(name);
3. If filtering by name is optional, omit the call rather than passing null.
4. Consider filtering by processDefinitionKey() instead if the value is actually a key.

Example fix

// before
ProcessDefinitionQuery query = repositoryService.createProcessDefinitionQuery()
    .processDefinitionName(params.get("name")); // may be null

// after
ProcessDefinitionQuery query = repositoryService.createProcessDefinitionQuery();
String name = params.get("name");
if (name != null && !name.isEmpty()) {
    query.processDefinitionName(name);
}

if (name == null || name.isEmpty()) {
    throw new BadRequestException("Process definition name is required");
}
List<ProcessDefinition> defs = repositoryService.createProcessDefinitionQuery().processDefinitionName(name).list();

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

try {
    return repositoryService.createProcessDefinitionQuery().processDefinitionName(name).list();
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null process definition name: {}", e.getMessage());
    throw new BadRequestException("name must not be null");
}

When it happens

Trigger: Calling processDefinitionName(null), usually when the name is taken from an optional query parameter, a localized label map miss, or config that names processes per environment.

Common situations: REST search endpoints forwarding absent 'name' params; i18n lookups returning null for an untranslated process label; environment-specific process-name configuration keys not set.

Related errors

• category is null
• Provided process definition id is null
• Provided process definition key is null
• categoryLike is null
• categoryNotEquals is null

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