flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided search key is null

Error message

Provided search key is null

What it means

BatchQueryImpl.searchKey() throws FlowableIllegalArgumentException with message 'Provided search key is null' when the searchKey argument is null. The search key is the batch's SEARCH_KEY_ column used for partitioned lookups (e.g. by document id); null is not a valid key and is rejected at setter time.

Solutions

1. Pass the non-null search key the batch was created with
2. Check Batch.getSearchKey() for null before querying by it; fall back to batchId if unset
3. Omit .searchKey(...) when key-based lookup is not required

Example fix

// before
Batch batch = batchService.createBatchQuery()
    .searchKey(documentId).singleResult(); // documentId may be null
// after
if (documentId == null) {
    throw new IllegalArgumentException("Document id required to look up batch by search key");
}
Batch batch = batchService.createBatchQuery()
    .searchKey(documentId).singleResult();

if (searchKey == null) {
    throw new IllegalArgumentException("searchKey is required for BatchQuery.searchKey()");
}
Batch batch = batchService.createBatchQuery().searchKey(searchKey).singleResult();

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

try {
    batch = batchService.createBatchQuery().searchKey(searchKey).singleResult();
} catch (FlowableIllegalArgumentException e) {
    // fall back to lookup by batchId or handle missing key
}

When it happens

Trigger: Calling createBatchQuery().searchKey(null), or forwarding a key derived from an entity/variable that is null (e.g. search key only set on batch parts, not the parent batch).

Common situations: Indexing/delete pipelines where the batch was created without a search key and later code queries by key anyway; copying searchKey from Batch.getSearchKey() which returns null when unset.

Related errors

• Involved groups are null
• Provided batch id is null
• Provided batch type is null
• Provided batch types must be provided and not empty
• Provided correlationId is null

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

Appendix: source

Thrown at modules/flowable-batch-service/src/main/java/org/flowable/batch/service/impl/BatchQueryImpl.java:95

            throw new FlowableIllegalArgumentException("Provided batch type is null");
        }
        this.batchType = batchType;
        return this;
    }

    @Override
    public BatchQuery batchTypes(Collection<String> batchTypes) {
        if (batchTypes == null || batchTypes.isEmpty()) {
            throw new FlowableIllegalArgumentException("Provided batch types must be provided and not empty");
        }
        this.batchTypes = batchTypes;
        return this;
    }

    @Override
    public BatchQuery searchKey(String searchKey) {
        if (searchKey == null) {
            throw new FlowableIllegalArgumentException("Provided search key is null");
        }
        this.searchKey = searchKey;
        return this;
    }
    
    @Override
    public BatchQuery searchKey2(String searchKey) {
        if (searchKey == null) {
            throw new FlowableIllegalArgumentException("Provided search key is null");
        }
        this.searchKey2 = searchKey;
        return this;
    }
    
    @Override
    public BatchQuery createTimeHigherThan(Date date) {
        if (date == null) {
            throw new FlowableIllegalArgumentException("Provided date is null");

View on GitHub (pinned to d6d39ce1c6)