{"record":{"id":"402084cb1c3a5f9f","repo":"flowable/flowable-engine","slug":"case-definition-key-is-null","errorCode":null,"errorMessage":"Case definition key is null","messagePattern":"Case definition key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java","lineNumber":184,"sourceCode":"    }\n\n    @Override\n    public HistoricCaseInstanceQuery caseDefinitionIds(Set<String> caseDefinitionIds) {\n        if (caseDefinitionIds == null) {\n            throw new FlowableIllegalArgumentException(\"Case definition ids is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.caseDefinitionIds = caseDefinitionIds;\n        } else {\n            this.caseDefinitionIds = caseDefinitionIds;\n        }\n        return this;\n    }\n\n    @Override\n    public HistoricCaseInstanceQueryImpl caseDefinitionKey(String caseDefinitionKey) {\n        if (caseDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Case definition key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.caseDefinitionKey = caseDefinitionKey;\n        } else {\n            this.caseDefinitionKey = caseDefinitionKey;\n        }\n        return this;\n    }\n    \n    @Override\n    public HistoricCaseInstanceQueryImpl caseDefinitionKeyLike(String caseDefinitionKeyLike) {\n        if (caseDefinitionKeyLike == null) {\n            throw new FlowableIllegalArgumentException(\"Case definition key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.caseDefinitionKeyLike = caseDefinitionKeyLike;\n        } else {\n            this.caseDefinitionKeyLike = caseDefinitionKeyLike;","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java#L166-L202","documentation":"HistoricCaseInstanceQueryImpl.caseDefinitionKey() validates that the case definition key is not null before storing it. Null keys would create an invalid equality predicate, so Flowable throws FlowableIllegalArgumentException eagerly.","triggerScenarios":"Calling caseDefinitionKey(null) or forwarding an unresolved key, e.g. a request parameter, path variable, or config entry that is absent.","commonSituations":"Building dynamic historic-case queries in services where the key comes from optional user input; copying code between process (BPMN) and case (CMMN) query APIs.","solutions":["Resolve a valid key first, or skip the call when the key is unknown","Use caseDefinitionKeyLike for partial matching only with a non-null value","Add a null guard around optional filters","Catch FlowableIllegalArgumentException for user-facing validation errors"],"exampleFix":"// before\nquery.caseDefinitionKey(params.get(\"caseKey\"));\n// after\nString key = params.get(\"caseKey\");\nif (key != null) {\n    query.caseDefinitionKey(key);\n}","handlingStrategy":"validation","validationCode":"if (caseDefinitionKey != null) {\n    query.caseDefinitionKey(caseDefinitionKey);\n}","typeGuard":"boolean hasKey = key != null && !key.isBlank();","tryCatchPattern":"try {\n    query.caseDefinitionKey(key);\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"Case definition key must not be null\", e);\n}","preventionTips":["Treat null as 'filter not set' and omit the call","Normalize empty strings to null at the API boundary","Keep filter-application logic in one guarded helper","Add tests for missing optional query fields"],"tags":["flowable","cmmn","null-check","query-api"],"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"}