flowable/flowable-engine · error · FlowableIllegalArgumentException

searchKey is null

Error message

searchKey is null

What it means

BatchPartQueryImpl.searchKey(String) filters batch parts by the batch search key. Passing null throws FlowableIllegalArgumentException immediately, as the library treats null as an invalid filter value rather than 'no filter'. Thrown at the searchKey(...) call site.

Source

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

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

    @Override
    public BatchPartQuery searchKey2(String searchKey2) {
        if (searchKey2 == null) {
            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");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Null-check the search key before applying the filter.
2. Build the query conditionally, omitting searchKey(...) when the value is absent.
3. Ensure batches that will be queried by search key are created with a non-null searchKey.

Example fix

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

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

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

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

When it happens

Trigger: Calling BatchPartQuery.searchKey(null), usually when the search key comes from a nullable variable, optional user input, or a lookup that returned nothing.

Common situations: Search forms where the key field was left empty; batch created without a searchKey so downstream lookups pass null; null return from a helper resolving the search key.

Related errors

• id is null
• batchId is null
• type is null
• searchKey2 is null
• batchType is null

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