{"record":{"id":"a7db21e106299fb4","repo":"flowable/flowable-engine","slug":"business-key-is-null-a7db21","errorCode":null,"errorMessage":"Business key is null","messagePattern":"Business key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":179,"sourceCode":"        if (processInstanceIds == null) {\n            throw new FlowableIllegalArgumentException(\"Set of process instance ids is null\");\n        }\n        if (processInstanceIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Set of process instance ids is empty\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.processInstanceIds = processInstanceIds;\n        } else {\n            this.processInstanceIds = processInstanceIds;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processInstanceBusinessKey(String businessKey) {\n        if (businessKey == null) {\n            throw new FlowableIllegalArgumentException(\"Business key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.businessKey = businessKey;\n        } else {\n            this.businessKey = businessKey;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processInstanceBusinessKey(String businessKey, String processDefinitionKey) {\n        if (businessKey == null) {\n            throw new FlowableIllegalArgumentException(\"Business key is null\");\n        }\n        if (inOrStatement) {\n            throw new FlowableIllegalArgumentException(\"This method is not supported in an OR statement\");\n        }\n","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L161-L197","documentation":"Flowable throws FlowableIllegalArgumentException when processInstanceBusinessKey(String) is called with a null businessKey. Query criteria setters in ProcessInstanceQueryImpl validate their arguments eagerly so that an invalid query fails at build time rather than at execution time with an obscure SQL error. Passing null here is always a bug because a null criterion means 'no filter', which the API forces you to express by simply not calling the setter.","triggerScenarios":"Calling processInstanceQuery.processInstanceBusinessKey(variableThatIsNull) — e.g. a method parameter, request parameter, or entity field that was never populated.","commonSituations":"Passing an optional HTTP query parameter straight through without a null check; a form/report field left empty; a refactored method whose businessKey argument became nullable; building queries generically from a map of criteria that contains a null value.","solutions":["Guard the call: only invoke processInstanceBusinessKey when the value is non-null, chaining conditionally on the query object.","Fix the upstream source so businessKey is populated (correct request mapping, form field, or entity load).","If an empty string is acceptable, normalize null to \"\" only if you truly want an equals-match on empty string.","If you intended no filtering, remove the call entirely instead of passing null."],"exampleFix":"// before\nProcessInstanceQuery q = runtimeService.createProcessInstanceQuery()\n    .processInstanceBusinessKey(businessKey);\n// after\nProcessInstanceQuery q = runtimeService.createProcessInstanceQuery();\nif (businessKey != null) {\n    q = q.processInstanceBusinessKey(businessKey);\n}","handlingStrategy":"validation","validationCode":"if (businessKey == null) {\n    throw new IllegalArgumentException(\"businessKey must be provided before building the query\");\n}\nProcessInstanceQuery q = runtimeService.createProcessInstanceQuery().processInstanceBusinessKey(businessKey);","typeGuard":"boolean hasBusinessKey(String s) { return s != null && !s.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.processInstanceBusinessKey(businessKey);\n} catch (FlowableIllegalArgumentException e) {\n    if (!e.getMessage().contains(\"Business key is null\")) throw e;\n    log.warn(\"No business key supplied; skipping business-key filter\");\n}","preventionTips":["Never pass null to query criteria setters; omit the call instead of expressing 'no filter' as null.","Null-check optional inputs (request params, entity fields) before building the query.","Wrap query building in a small builder/helper that applies filters only for non-null values.","Add unit tests covering null filter values."],"tags":["flowable","null-check","query-api","validation"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}