{"record":{"id":"db4c21b8e1074f42","repo":"flowable/flowable-engine","slug":"provided-search-key-is-null","errorCode":null,"errorMessage":"Provided search key is null","messagePattern":"Provided search key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-batch-service/src/main/java/org/flowable/batch/service/impl/BatchQueryImpl.java","lineNumber":95,"sourceCode":"            throw new FlowableIllegalArgumentException(\"Provided batch type is null\");\n        }\n        this.batchType = batchType;\n        return this;\n    }\n\n    @Override\n    public BatchQuery batchTypes(Collection<String> batchTypes) {\n        if (batchTypes == null || batchTypes.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Provided batch types must be provided and not empty\");\n        }\n        this.batchTypes = batchTypes;\n        return this;\n    }\n\n    @Override\n    public BatchQuery searchKey(String searchKey) {\n        if (searchKey == null) {\n            throw new FlowableIllegalArgumentException(\"Provided search key is null\");\n        }\n        this.searchKey = searchKey;\n        return this;\n    }\n    \n    @Override\n    public BatchQuery searchKey2(String searchKey) {\n        if (searchKey == null) {\n            throw new FlowableIllegalArgumentException(\"Provided search key is null\");\n        }\n        this.searchKey2 = searchKey;\n        return this;\n    }\n    \n    @Override\n    public BatchQuery createTimeHigherThan(Date date) {\n        if (date == null) {\n            throw new FlowableIllegalArgumentException(\"Provided date is null\");","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-batch-service/src/main/java/org/flowable/batch/service/impl/BatchQueryImpl.java#L77-L113","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass the non-null search key the batch was created with","Check Batch.getSearchKey() for null before querying by it; fall back to batchId if unset","Omit .searchKey(...) when key-based lookup is not required"],"exampleFix":"// before\nBatch batch = batchService.createBatchQuery()\n    .searchKey(documentId).singleResult(); // documentId may be null\n// after\nif (documentId == null) {\n    throw new IllegalArgumentException(\"Document id required to look up batch by search key\");\n}\nBatch batch = batchService.createBatchQuery()\n    .searchKey(documentId).singleResult();","handlingStrategy":"validation","validationCode":"if (searchKey == null) {\n    throw new IllegalArgumentException(\"searchKey is required for BatchQuery.searchKey()\");\n}\nBatch batch = batchService.createBatchQuery().searchKey(searchKey).singleResult();","typeGuard":"boolean hasSearchKey(String k) { return k != null && !k.isEmpty(); }","tryCatchPattern":"try {\n    batch = batchService.createBatchQuery().searchKey(searchKey).singleResult();\n} catch (FlowableIllegalArgumentException e) {\n    // fall back to lookup by batchId or handle missing key\n}","preventionTips":["Remember searchKey is optional at batch creation — check Batch.getSearchKey() for null before re-querying by it","Use a fallback lookup path (batchId) when the key was never set","Ensure the variable/entity feeding the search key is populated upstream"],"tags":["java","flowable","null-check","query-api"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}