{"record":{"id":"54096ff7a84c5319","repo":"Activiti/Activiti","slug":"business-key-is-null-54096f","errorCode":null,"errorMessage":"Business key is null","messagePattern":"Business key is null","errorType":"validation","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":137,"sourceCode":"    public ProcessInstanceQuery processInstanceIds(Set<String> processInstanceIds) {\n        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    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    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\n        this.businessKey = businessKey;","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/Activiti/Activiti/blob/56435b1a97deeafdc09dd40074b056c89fba5a8a/activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java#L119-L155","documentation":"ProcessInstanceQueryImpl.processInstanceBusinessKey(String) throws ActivitiIllegalArgumentException when the businessKey argument is null. A null business key cannot be used as a query filter, so Activiti validates eagerly. This keeps query construction deterministic instead of failing later in the database layer.","triggerScenarios":"Calling createProcessInstanceQuery().processInstanceBusinessKey(key) with key == null — usually a businessKey variable sourced from an unconfigured process variable, request parameter, or message header.","commonSituations":"REST controllers binding a missing query parameter to null; message-driven process starts where the correlation business key was absent; configuration where the business key mapping was never set.","solutions":["Validate the business key (null/blank) before building the query and return a clear client-side error if absent","Only add the filter when present: if (businessKey != null) query = query.processInstanceBusinessKey(businessKey);","Fix the upstream source (request validation, variable mapping) so the key is always populated when this path runs","Catch ActivitiIllegalArgumentException and translate it into your API's 400 response"],"exampleFix":"// before\nif (businessKey != null) {\n    query = query.processInstanceBusinessKey(businessKey);\n}\n// after\nif (businessKey == null) {\n    throw new BadRequestException(\"businessKey is required\");\n}\nquery = query.processInstanceBusinessKey(businessKey);","handlingStrategy":"validation","validationCode":"if (businessKey == null || businessKey.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"businessKey is required\");\n}","typeGuard":"boolean hasBusinessKey(String key) { return key != null && !key.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.processInstanceBusinessKey(businessKey);\n} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Business key is null\")) {\n        throw new BadRequestException(\"businessKey query parameter is required\");\n    }\n    throw e;\n}","preventionTips":["Validate request parameters before they reach query construction","Make business key fields required in API validation annotations (@NotNull/@NotBlank)","Conditionally apply optional business-key filters instead of passing null","Trace business key provenance (variables, headers) and assert non-null at boundaries"],"tags":["activiti","query","null-argument","business-key"],"backgroundTag":"null-argument","analyzedSha":"56435b1a97deeafdc09dd40074b056c89fba5a8a","analyzedAt":"2026-09-09T21:00:06.703Z","contentChangedAt":"2026-09-09T21:00:06.703Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}