flowable/flowable-engine · error · FlowableIllegalArgumentException

deploymentCategory is null

Error message

deploymentCategory is null

What it means

DeploymentQueryImpl.deploymentCategory(String) throws FlowableIllegalArgumentException when the deploymentCategory argument is null. Deployments can be categorized at deploy time; this filter matches the exact category, and null is rejected eagerly at builder time rather than producing a null-equality SQL predicate.

Solutions

1. Pass a concrete category string that was set via DeploymentBuilder.category(...).
2. Guard the call: only add the category filter when it is non-null.
3. Fix the deployment process so the expected category is always set.

Example fix

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

if (category != null && !category.isEmpty()) {
    query.deploymentCategory(category);
}

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

try {
    query.deploymentCategory(category);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null deployment category filter ignored", e);
}

When it happens

Trigger: repositoryService.createDeploymentQuery().deploymentCategory(null), usually when the category is read from configuration or model metadata that is missing.

Common situations: Deployments deployed without a category while query code assumes one exists; multi-environment setups where the category property is defined in prod but not dev.

Related errors

• deploymentCategoryExclude is null
• callbackId is null
• Candidate group is null
• Candidate group list is null
• Candidate user is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/DeploymentQueryImpl.java:105

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

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

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

    @Override
    public DeploymentQueryImpl deploymentCategoryLike(String categoryLike) {
        if (categoryLike == null) {
            throw new FlowableIllegalArgumentException("deploymentCategoryLike is null");
        }
        this.categoryLike = categoryLike;
        return this;
    }

    @Override
    public DeploymentQueryImpl deploymentCategoryNotEquals(String deploymentCategoryNotEquals) {
        if (deploymentCategoryNotEquals == null) {
            throw new FlowableIllegalArgumentException("deploymentCategoryExclude is null");

View on GitHub (pinned to d6d39ce1c6)