What causes "Deployment ids is null" in flowable/flowable-engine?

Pass a non-null List of deployment ids, e.g. Arrays.asList("dep-1", "dep-2").

flowable/flowable-engine · error · FlowableIllegalArgumentException

Deployment ids is null

Error message

Deployment ids is null

What it means

HistoricCaseInstanceQueryImpl.deploymentIds() throws FlowableIllegalArgumentException when the List of deployment ids is null. The list feeds an SQL IN clause, so a null value is rejected before assignment to the query or the active or-query object. Only null is checked — an empty list passes this specific guard.

Source

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

    }

    @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;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQueryImpl finished() {
        if (inOrStatement) {
            this.currentOrQueryObject.finished = true;
        } else {
            this.finished = true;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Pass a non-null List of deployment ids, e.g. Arrays.asList("dep-1", "dep-2").
Initialize collections at declaration (Collections.emptyList()) instead of leaving them null.
Skip the deploymentIds call when the list is null/empty to apply no filter.
Catch FlowableIllegalArgumentException when filters come from external input.

Example fix

// before
query.deploymentIds(ids);
// after
List<String> ids = resolveDeploymentIds();
if (ids != null && !ids.isEmpty()) {
    query.deploymentIds(ids);
}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean hasDeploymentIds(List<String> ids) {
    return ids != null && !ids.isEmpty();
}

Try / catch

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

Prevention

Initialize id lists as empty collections, never null
Map streams defensively: return emptyList() instead of null when nothing matches
Guard multi-id filters with null and isEmpty checks
Unit-test export/report jobs with empty deployment scopes

When it happens

Trigger: Calling deploymentIds(null), typically when the list is built by collecting ids from a stream/filter whose result object was null, or from an absent request body field.

Common situations: Bulk history exports scoped to several deployments; the id list is assembled from configuration or a previous query, and an upstream failure leaves it null instead of empty.

Related errors

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