flowable/flowable-engine · error · FlowableIllegalArgumentException

batchId is null

Error message

batchId is null

What it means

BatchPartQueryImpl.batchId(String) filters batch parts by their parent batch. Passing null throws FlowableIllegalArgumentException because a null filter is ambiguous — the library refuses to silently ignore it or match nothing. It is thrown at the batchId(...) call site, not at query execution.

Source

Thrown at modules/flowable-batch-service/src/main/java/org/flowable/batch/service/impl/BatchPartQueryImpl.java:76

    @Override
    public List<BatchPart> executeList(CommandContext commandContext) {
        return batchServiceConfiguration.getBatchPartEntityManager().findBatchPartsByQueryCriteria(this);
    }

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

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

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

    @Override
    public BatchPartQuery searchKey(String searchKey) {
        if (searchKey == null) {
            throw new FlowableIllegalArgumentException("searchKey is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Null-check the batchId before calling batchId(...); if absent, either abort or run the query without the filter as appropriate.
2. Resolve the parent Batch first (createBatchQuery().batchId(id).singleResult()) and check it is non-null before querying its parts.
3. Validate that the batch-creation path actually returned an id.

Example fix

// before
List<BatchPart> parts = batchService.createBatchPartQuery()
    .batchId(parentBatchId).list();
// after
if (parentBatchId != null) {
    List<BatchPart> parts = batchService.createBatchPartQuery()
        .batchId(parentBatchId).list();
}

if (batchId != null) {
    parts = batchService.createBatchPartQuery().batchId(batchId).list();
} else {
    throw new IllegalArgumentException("batchId is required");
}

boolean hasBatchId(String batchId) {
    return batchId != null && !batchId.isEmpty();
}

try {
    List<BatchPart> parts = query.batchId(batchId).list();
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    throw new IllegalArgumentException("batchId must not be null when filtering batch parts", e);
}

When it happens

Trigger: Calling BatchPartQuery.batchId(null), usually when the batch id originates from a nullable variable, an optional lookup of the parent batch, or a request parameter.

Common situations: Listing parts of a batch whose id lookup failed (singleResult() on empty query returned null); controllers forwarding missing query params; code that assumed the batch always exists.

Related errors

• id is null
• type is null
• searchKey is null
• searchKey2 is null
• batchType is null

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