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

Pass a non-null name string, or omit the deploymentName() call entirely when filtering by name is optional

flowable/flowable-engine · error · FlowableIllegalArgumentException

deploymentName is null

Error message

deploymentName is null

What it means

FlowableIllegalArgumentException thrown by CmmnDeploymentQueryImpl.deploymentName when the deploymentName argument is null. The exact-name filter requires a non-null string; null is not accepted as 'no filter'. Fail-fast validation on the query builder.

Solutions

Pass a non-null name string, or omit the deploymentName() call entirely when filtering by name is optional
Default the value to a concrete string if a name is always required
Validate upstream input so null never reaches the query

Example fix

// before
query.deploymentName(nameParam); // may be null
// after
if (nameParam != null) { query.deploymentName(nameParam); } // or deploymentNameLike(nameParam)

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
    query.deploymentName(name);
} catch (FlowableIllegalArgumentException e) {
    if ("deploymentName is null".equals(e.getMessage())) {
        throw new IllegalArgumentException("deploymentName must not be null; omit the filter instead", e);
    }
    throw e;
}

Prevention

Make optional name filters conditional on non-null input
Default request/config values to empty-string-plus-skip rather than null
Document that null means invalid, not 'match all'
Sanitize user input before passing it into queries

When it happens

Trigger: Calling createDeploymentQuery().deploymentName(null), usually because the name came from an unset configuration value, empty request parameter mapped to null, or unpopulated variable.

Common situations: Optional name filters where null should mean 'no filter', form/API inputs not defaulted, config keys missing that feed the query.

Related errors

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

Appendix: source

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

            throw new FlowableIllegalArgumentException("Deployment id is null");
        }
        this.deploymentId = deploymentId;
        return this;
    }
    
    @Override
    public CmmnDeploymentQueryImpl deploymentIds(List<String> deploymentIds) {
        if (deploymentIds == null) {
            throw new FlowableIllegalArgumentException("Deployment ids is null");
        }
        this.deploymentIds = deploymentIds;
        return this;
    }

    @Override
    public CmmnDeploymentQueryImpl deploymentName(String deploymentName) {
        if (deploymentName == null) {
            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");

View on GitHub (pinned to d6d39ce1c6)