flowable/flowable-engine · error · FlowableIllegalArgumentException

batchSearchKey is null

Error message

batchSearchKey is null

What it means

BatchPartQueryImpl.batchSearchKey(String) filters batch parts by the parent batch's search key. Passing null throws FlowableIllegalArgumentException at the call site, since null filters are rejected by the query API. Note the parameter is named searchKey locally but validates against the batchSearchKey message.

Solutions

1. Null-check the search key before applying the batchSearchKey filter.
2. Skip the filter when the value is absent (conditional query building).
3. Ensure batches that will be queried this way are created with a non-null searchKey.

Example fix

// before
BatchPartQuery q = batchService.createBatchPartQuery().batchSearchKey(key);
// after
BatchPartQuery q = batchService.createBatchPartQuery();
if (key != null) {
    q.batchSearchKey(key);
}

BatchPartQuery query = batchService.createBatchPartQuery();
if (batchSearchKey != null) {
    query.batchSearchKey(batchSearchKey);
}
List<BatchPart> parts = query.list();

boolean hasBatchSearchKey(String k) {
    return k != null && !k.isEmpty();
}

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

When it happens

Trigger: Calling BatchPartQuery.batchSearchKey(null), typically with a search key sourced from user input, configuration, or a lookup that returned null.

Common situations: Empty search fields in UIs; batches created without a batch-level searchKey then queried by it; null propagation from a resolver method.

Related errors

• batchId is null
• batchSearchKey2 is null
• batchType is null
• id is null
• searchKey is null

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

Appendix: source

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

            throw new FlowableIllegalArgumentException("searchKey2 is null");
        }
        this.searchKey2 = searchKey2;
        return this;
    }

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

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

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

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

View on GitHub (pinned to d6d39ce1c6)