flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process definition category is null

Error message

Process definition category is null

What it means

ProcessInstanceQueryImpl.processDefinitionCategory(String) throws ActivitiIllegalArgumentException when the processDefinitionCategory argument is null. Filter values in the query API must be concrete values; null means 'no filter' and is expressed by simply not calling the method. The check happens immediately so invalid queries fail at build time.

Source

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

            this.tenantIdLike = tenantIdLike;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceWithoutTenantId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutTenantId = true;
        } else {
            this.withoutTenantId = true;
        }
        return this;
    }

    @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;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Only call processDefinitionCategory when a non-null category is available (conditional chaining).
2. Treat an absent category as 'no filter' and omit the call instead of passing null.
3. Validate/normalize request input upstream (reject nulls or map them to 'all').
4. Catch ActivitiIllegalArgumentException around query building and return a 400-style validation error.

Example fix

// before
query.processDefinitionCategory(category); // category may be null
// after
if (category != null) {
    query = query.processDefinitionCategory(category);
}

if (category == null) {
    // omit filter entirely
} else {
    query = query.processDefinitionCategory(category);
}

boolean hasCategory(String category) { return category != null && !category.trim().isEmpty(); }

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

When it happens

Trigger: Calling .processDefinitionCategory(null) — usually a category value pulled from a request parameter, saved filter, or database row that is null.

Common situations: REST endpoints forwarding unvalidated query params into process instance queries; stored search filters where the category field was never populated; null vs empty-string confusion when mapping form data.

Related errors

• process instance tenant id is null
• Process definition name 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/4a01963f5f21bde0. Report an issue: GitHub.