flowable/flowable-engine · error · FlowableIllegalArgumentException

batchSearchKey2 is null

Error message

batchSearchKey2 is null

What it means

BatchPartQueryImpl.batchSearchKey2(String) filters batch parts by the parent batch's secondary search key. Passing null throws FlowableIllegalArgumentException at the batchSearchKey2(...) call, mirroring all other null-filter guards in this query class. The error occurs before the query executes.

Solutions

1. Null-check the value before calling batchSearchKey2(...).
2. Build the query conditionally, omitting the filter when the value is null.
3. If 'no secondary key' must be matched, query without the filter and post-filter in application code.

Example fix

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

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

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

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

When it happens

Trigger: Calling BatchPartQuery.batchSearchKey2(null), usually when the secondary batch search key is treated as optional upstream but passed unconditionally.

Common situations: Optional search criteria assumed to be nullable-safe; batches created without searchKey2; blank form inputs forwarded directly to the query.

Related errors

• batchId is null
• batchSearchKey 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/bc8788a5d5b16c18. Report an issue: GitHub.

Appendix: source

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

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

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

View on GitHub (pinned to d6d39ce1c6)