What causes "deploymentCategory is null" in flowable/flowable-engine?

Pass a non-null deployment category string to deploymentCategory()

flowable/flowable-engine · error · FlowableIllegalArgumentException

deploymentCategory is null

Error message

deploymentCategory is null

What it means

Flowable throws this FlowableIllegalArgumentException when CmmnDeploymentQueryImpl.deploymentCategory(null) is called. Query criteria setters validate that the supplied filter value is non-null; a null category would produce an ambiguous SQL filter, so the library fails fast at query-build time instead of returning wrong results.

Solutions

Pass a non-null deployment category string to deploymentCategory()
If the category filter is optional, wrap the setter in an if (category != null) check
For the 'not set' case, simply omit the deploymentCategory() call instead of passing null

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

Objects.requireNonNull(category, "deploymentCategory must not be null");
query.deploymentCategory(category);

Type guard

boolean hasCategory = category != null && !category.isEmpty();

Try / catch

try {
    query.deploymentCategory(category);
} catch (FlowableIllegalArgumentException e) {
    // fall back to unfiltered query or surface a 400 to the caller
}

Prevention

Null-check optional filter values before calling query setters
Only invoke setter methods for filters you actually want to apply
Centralize query building in a helper that skips null filters

When it happens

Trigger: Calling repositoryService.createCmmnDeploymentQuery().deploymentCategory(null), typically when the category value comes from an uninitialized variable, a missing configuration entry, or an unmarshalled request field.

Common situations: Building dynamic queries where the category filter is optional but the developer calls the setter unconditionally with a possibly-null variable; REST/API layers passing through null client parameters.

Related errors

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/repository/CmmnDeploymentQueryImpl.java:99

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

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

    @Override
    public CmmnDeploymentQueryImpl deploymentCategory(String deploymentCategory) {
        if (deploymentCategory == null) {
            throw new FlowableIllegalArgumentException("deploymentCategory is null");
        }
        this.category = deploymentCategory;
        return this;
    }

    @Override
    public CmmnDeploymentQueryImpl deploymentCategoryNotEquals(String deploymentCategoryNotEquals) {
        if (deploymentCategoryNotEquals == null) {
            throw new FlowableIllegalArgumentException("deploymentCategoryExclude is null");
        }
        this.categoryNotEquals = deploymentCategoryNotEquals;
        return this;
    }
    
    @Override
    public CmmnDeploymentQueryImpl deploymentKey(String deploymentKey) {
        if (deploymentKey == null) {
            throw new FlowableIllegalArgumentException("deploymentKey is null");

View on GitHub (pinned to d6d39ce1c6)