{"record":{"id":"aedb06345b1e4242","repo":"flowable/flowable-engine","slug":"provided-case-definition-key-is-null-aedb06","errorCode":null,"errorMessage":"Provided case definition key is null","messagePattern":"Provided case definition key is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java","lineNumber":347,"sourceCode":"        scopeId(caseInstanceId);\n        scopeType(ScopeTypes.CMMN);\n        return this;\n    }\n    \n    @Override\n    public SuspendedJobQueryImpl caseDefinitionId(String caseDefinitionId) {\n        if (caseDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided case definition id is null\");\n        }\n        scopeDefinitionId(caseDefinitionId);\n        scopeType(ScopeTypes.CMMN);\n        return this;\n    }\n\n    @Override\n    public SuspendedJobQueryImpl caseDefinitionKey(String caseDefinitionKey) {\n        if (caseDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Provided 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 SuspendedJobQueryImpl planItemInstanceId(String planItemInstanceId) {\n        if (planItemInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided plan item instance id is null\");\n        }\n        subScopeId(planItemInstanceId);\n        scopeType(ScopeTypes.CMMN);\n        return this;\n    }","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java#L329-L365","documentation":"This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.caseDefinitionKey() when the caller passes a null definition key. The key is the business identifier of a case definition and must be non-null for a valid filter. As with all Flowable query setters, validation happens immediately during query construction, not at list()/count() time.","triggerScenarios":"Calling suspendedJobQuery().caseDefinitionKey(null), usually when the key came from an unset configuration property, a missing request parameter, or a lookup that returned null.","commonSituations":"Properties/YAML configuration with a missing key value; REST clients omitting the key; version upgrades where the key source changed from required to optional.","solutions":["Guard the call: only apply caseDefinitionKey() when non-null","Resolve the key from configuration with a validated default or fail earlier with a clearer message","Use caseDefinitionId() when you actually hold an id rather than a key","Validate required inputs at the entry point of your service"],"exampleFix":"// before\nquery.caseDefinitionKey(definitionKey); // may be null\n// after\nif (definitionKey != null) {\n    query.caseDefinitionKey(definitionKey);\n}","handlingStrategy":"validation","validationCode":"if (caseDefinitionKey != null) {\n    query.caseDefinitionKey(caseDefinitionKey);\n}","typeGuard":"boolean hasCaseDefinitionKey = caseDefinitionKey != null && !caseDefinitionKey.isBlank();","tryCatchPattern":"try {\n    query.caseDefinitionKey(caseDefinitionKey);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"case definition key is null\")) {\n        // rebuild query without key filter or raise a config error\n    } else {\n        throw e;\n    }\n}","preventionTips":["Load definition keys from configuration with required-value validation at startup","Null-check map/lookup results before passing keys into queries","Use Objects.requireNonNull on required inputs at your own API boundary for clearer errors","Skip the filter explicitly when no key restriction is intended"],"tags":["java","flowable","query","null-check","cmmn"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}