{"record":{"id":"58030b535ab23f6d","repo":"flowable/flowable-engine","slug":"business-key-is-null-58030b","errorCode":null,"errorMessage":"Business key is null","messagePattern":"Business key is null","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":129,"sourceCode":"        if (processInstanceIds == null) {\n            throw new ActivitiIllegalArgumentException(\"Set of process instance ids is null\");\n        }\n        if (processInstanceIds.isEmpty()) {\n            throw new ActivitiIllegalArgumentException(\"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 ActivitiIllegalArgumentException(\"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 ActivitiIllegalArgumentException(\"Business key is null\");\n        }\n        if (inOrStatement) {\n            throw new ActivitiIllegalArgumentException(\"This method is not supported in an OR statement\");\n        }\n","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java#L111-L147","documentation":"processInstanceBusinessKey(businessKey) filters process instances by business key. It throws ActivitiIllegalArgumentException('Business key is null') for a null key, since a null business key cannot be used as an equality filter.","triggerScenarios":"Calling ProcessInstanceQuery.processInstanceBusinessKey(null), typically when the business key originates from an external reference (order id, document id) that was absent in the incoming request or message.","commonSituations":"Correlating external domain entities with workflow instances where the reference field is optional; message-driven resolvers that dropped the key attribute.","solutions":["Pass the real business key string used when the process was started","If the key is optional, build the query without the business-key filter instead of passing null","Validate the incoming reference (non-null, correct format) before querying","Catch ActivitiIllegalArgumentException and map it to a 400-style validation error"],"exampleFix":"// before\nruntimeService.createProcessInstanceQuery()\n    .processInstanceBusinessKey(orderRef.getBusinessKey()) // may be null\n    .singleResult();\n// after\nif (orderRef.getBusinessKey() != null) {\n    runtimeService.createProcessInstanceQuery()\n        .processInstanceBusinessKey(orderRef.getBusinessKey())\n        .singleResult();\n}","handlingStrategy":"validation","validationCode":"if (businessKey == null) {\n    throw new IllegalArgumentException(\"businessKey is required\");\n}\nquery.processInstanceBusinessKey(businessKey);","typeGuard":"boolean hasBusinessKey(String bk) { return bk != null && !bk.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.processInstanceBusinessKey(bk);\n} catch (ActivitiIllegalArgumentException e) {\n    throw new BadRequestException(\"businessKey is mandatory for correlation lookup\");\n}","preventionTips":["Make the business key a required field on domain entities that start processes","Validate external references at the API boundary","Log correlation lookups with their key so missing keys are visible"],"tags":["java","activiti","query","null-argument","business-key"],"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"}