flowable/flowable-engine · error · FlowableIllegalArgumentException

Deployment id is null

Error message

Deployment id is null

What it means

HistoricCaseInstanceQueryImpl.deploymentId() rejects a null deployment id with FlowableIllegalArgumentException. The deployment id filter is translated into an equality predicate, so Flowable validates non-null before storing the value on the query or on currentOrQueryObject within an or() block.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:549

            this.caseInstanceParentId = parentId;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQuery withoutCaseInstanceParent() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutCaseInstanceParentId = true;
        } else {
            this.withoutCaseInstanceParentId = true;
        }
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a real deployment id, e.g. deploymentId(repositoryService.createDeploymentQuery()...singleResult().getId()).
2. Only call deploymentId when the id is non-null; otherwise omit the filter.
3. Fail fast upstream with a clear message if the deployment id is required for the operation.
4. Catch FlowableIllegalArgumentException to convert the failure into a 400 validation response.

Example fix

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

if (deploymentId != null) {
    query.deploymentId(deploymentId);
}

boolean hasDeploymentId(String id) {
    return id != null && !id.isBlank();
}

try {
    query.deploymentId(deploymentId);
} catch (FlowableIllegalArgumentException e) {
    throw new InvalidRequestException("deploymentId must not be null");
}

When it happens

Trigger: Calling deploymentId(null) — for example when the deployment id comes from a resolver that failed, an unset request attribute, or a null return from a deployment lookup service.

Common situations: Environment-scoped history views filtered by the deployment that provisioned the process; after a failed deployment or migration, the id lookup returns null and is passed to the query.

Related errors

• query is null
• parentScopeIds is null or empty
• Business status is null
• Case definition keys is null
• Parent id is null

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