{"record":{"id":"32638b402b6a6c95","repo":"flowable/flowable-engine","slug":"business-key-is-null-32638b","errorCode":null,"errorMessage":"Business key is null","messagePattern":"Business key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceQueryImpl.java","lineNumber":425,"sourceCode":"    }\n\n    @Override\n    public CaseInstanceQuery caseInstanceParentScopeIds(Set<String> parentScopeIds) {\n        if (parentScopeIds == null || parentScopeIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"parentScopeIds is null or empty\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.parentScopeIds = parentScopeIds;\n        } else {\n            this.parentScopeIds = parentScopeIds;\n        }\n        return this;\n    }\n\n    @Override\n    public CaseInstanceQueryImpl caseInstanceBusinessKey(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 CaseInstanceQueryImpl caseInstanceBusinessKeyLike(String businessKeyLike) {\n        if (businessKeyLike == null) {\n            throw new FlowableIllegalArgumentException(\"Business key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.businessKeyLike = businessKeyLike;\n        } else {\n            this.businessKeyLike = businessKeyLike;","sourceCodeStart":407,"sourceCodeEnd":443,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceQueryImpl.java#L407-L443","documentation":"Flowable's CaseInstanceQueryImpl throws FlowableIllegalArgumentException when caseInstanceBusinessKey(String) is called with null. The business key is a user-defined correlation value stored on case instances; filtering by a null key is meaningless, so the engine validates the argument immediately. Pass a concrete business key string.","triggerScenarios":"Calling caseInstanceBusinessKey(null) directly; forwarding an unvalidated request parameter or DTO field that was not supplied; using a variable that was supposed to hold the business key but was never set.","commonSituations":"REST/search endpoints where the client omitted the businessKey parameter and the controller passes it straight into the query; config or form field not mapped; tests constructing queries programmatically with placeholder values; mixing up businessKey and businessStatus fields.","solutions":["Check the value for null before calling; only add the business-key criterion when a key is actually present","Return a client-side validation error if businessKey is a mandatory filter in your API","If any business key is acceptable, omit the criterion instead of passing null","Confirm you are reading the correct field from your DTO/request object"],"exampleFix":"// before\nquery.caseInstanceBusinessKey(request.getBusinessKey()); // may be null\n// after\nString businessKey = request.getBusinessKey();\nif (businessKey != null) {\n    query.caseInstanceBusinessKey(businessKey);\n}","handlingStrategy":"validation","validationCode":"if (businessKey == null || businessKey.isBlank()) {\n    throw new IllegalArgumentException(\"businessKey must be provided\");\n}\nquery.caseInstanceBusinessKey(businessKey);","typeGuard":"boolean hasText(String s) {\n    return s != null && !s.trim().isEmpty();\n}","tryCatchPattern":"try {\n    query.caseInstanceBusinessKey(businessKey);\n} catch (FlowableIllegalArgumentException e) {\n    throw new ResponseStatusException(HttpStatus.BAD_REQUEST, \"businessKey filter must not be null\");\n}","preventionTips":["Null-check optional request parameters before applying query filters","Make business key a required, validated parameter when filtering by it is mandatory","Omit the criterion when no business key filter is intended","Keep businessKey and businessStatus fields distinct in DTOs to avoid mix-ups"],"tags":["flowable","cmmn","query","null-check","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"}