{"record":{"id":"6fa16d89b46d9c97","repo":"flowable/flowable-engine","slug":"business-key-is-null-6fa16d","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/ExecutionQueryImpl.java","lineNumber":342,"sourceCode":"    }\n\n    @Override\n    public ExecutionQueryImpl rootProcessInstanceId(String rootProcessInstanceId) {\n        if (rootProcessInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Root process instance id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.rootProcessInstanceId = rootProcessInstanceId;\n        } else {\n            this.rootProcessInstanceId = rootProcessInstanceId;\n        }\n        return this;\n    }\n\n    @Override\n    public ExecutionQuery 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 ExecutionQuery processInstanceBusinessKey(String processInstanceBusinessKey, boolean includeChildExecutions) {\n        if (!includeChildExecutions) {\n            return processInstanceBusinessKey(processInstanceBusinessKey);\n        } else {\n            if (processInstanceBusinessKey == null) {\n                throw new FlowableIllegalArgumentException(\"Business key is null\");\n            }\n            ","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java#L324-L360","documentation":"ExecutionQueryImpl.processInstanceBusinessKey(String) throws FlowableIllegalArgumentException when the business key is null. The business key filter maps to a WHERE condition on ACT_RU_EXECUTION.BUSINESS_KEY_, so a null value cannot be translated into a meaningful predicate. Flowable validates eagerly so the error surfaces at query build time, not at list()/singleResult().","triggerScenarios":"Calling processInstanceBusinessKey(null), usually when the business key originates from external input, a form field, or an upstream variable that was never set.","commonSituations":"REST endpoints with optional business-key params passed straight into the query; legacy data lacking business keys; refactor where a default constant was removed.","solutions":["Validate the business key is non-null/non-blank before building the query","For optional keys, only add the filter when present (conditional query building)","Sanitize/trim empty strings to null consciously and branch on it","Catch FlowableIllegalArgumentException to convert it into a 400-style response"],"exampleFix":"// before\nExecutionQuery query = runtimeService.createExecutionQuery().processInstanceBusinessKey(businessKey);\n// after\nExecutionQuery query = runtimeService.createExecutionQuery();\nif (businessKey != null && !businessKey.isBlank()) {\n    query.processInstanceBusinessKey(businessKey);\n}","handlingStrategy":"validation","validationCode":"if (businessKey == null || businessKey.isBlank()) {\n    throw new IllegalArgumentException(\"businessKey must not be null or blank\");\n}","typeGuard":"boolean hasBusinessKey(String key) {\n    return key != null && !key.isBlank();\n}","tryCatchPattern":"try {\n    Execution exec = runtimeService.createExecutionQuery().processInstanceBusinessKey(key).singleResult();\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"businessKey is required\", e);\n}","preventionTips":["Validate business keys at the REST/service boundary before querying","Build the query conditionally when the key is optional","Trim and normalize keys to avoid blank-string surprises"],"tags":["flowable","null-check","business-key","query"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T16:30:33.424Z"}