flowable/flowable-engine · error · FlowableIllegalArgumentException

deploymentKey is null

Error message

deploymentKey is null

What it means

DeploymentQueryImpl.deploymentKey(String) throws FlowableIllegalArgumentException when the deploymentKey argument is null. Deployments may carry a key (set via DeploymentBuilder.key(...)); this filter matches it exactly, and Flowable validates the argument eagerly at builder time so null never reaches SQL execution.

Solutions

1. Pass a non-null key string that was set at deploy time via DeploymentBuilder.key(...).
2. Guard: if (deploymentKey != null) query.deploymentKey(deploymentKey).
3. If the target deployment has no key, filter by name or id instead.

Example fix

// before
query.deploymentKey(deploymentKey); // throws when null
// after
if (deploymentKey != null) {
    query.deploymentKey(deploymentKey);
}

if (deploymentKey == null || deploymentKey.isEmpty()) {
    throw new IllegalArgumentException("A non-empty deployment key is required");
}

boolean isValidDeploymentKey(String key) { return key != null && !key.trim().isEmpty(); }

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

When it happens

Trigger: repositoryService.createDeploymentQuery().deploymentKey(null), usually when the key comes from process definition metadata, a request parameter, or a lookup that returned null.

Common situations: Older deployments created before keys were introduced (key is null in the DB while query code assumes one); model/config fields for the key not populated.

Related errors

• callbackId is null
• Candidate group is null
• Candidate group list is null
• Candidate user is null
• Deployment id is null

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

Appendix: source

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

            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");
        }
        this.categoryNotEquals = deploymentCategoryNotEquals;
        return this;
    }

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

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

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

View on GitHub (pinned to d6d39ce1c6)