{"record":{"id":"186e954a2a51aad5","repo":"flowable/flowable-engine","slug":"provided-scope-definitionid-is-null","errorCode":null,"errorMessage":"Provided scope definitionid is null","messagePattern":"Provided scope definitionid is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java","lineNumber":311,"sourceCode":"            this.scopeType = scopeType;\n        }\n        return this;\n    }\n\n    @Override\n    public DeadLetterJobQueryImpl withoutScopeType() {\n        if (inOrStatement) {\n            this.currentOrQueryObject.withoutScopeType = true;\n        } else {\n            this.withoutScopeType = true;\n        }\n        return this;\n    }\n\n    @Override\n    public DeadLetterJobQueryImpl scopeDefinitionId(String scopeDefinitionId) {\n        if (scopeDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided scope definitionid is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.scopeDefinitionId = scopeDefinitionId;\n        } else {\n            this.scopeDefinitionId = scopeDefinitionId;\n        }\n        return this;\n    }\n\n    @Override\n    public DeadLetterJobQuery caseInstanceId(String caseInstanceId) {\n        if (caseInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided case instance id is null\");\n        }\n        scopeId(caseInstanceId);\n        scopeType(ScopeTypes.CMMN);\n        return this;\n    }","sourceCodeStart":293,"sourceCodeEnd":329,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java#L293-L329","documentation":"DeadLetterJobQueryImpl.scopeDefinitionId() throws FlowableIllegalArgumentException when the scopeDefinitionId parameter is null. Flowable query builders validate required filter arguments eagerly so that an invalid query fails at construction time rather than producing an empty or malformed SQL query at execution time. Passing null here indicates the caller resolved no definition id (e.g. a case/process definition lookup returned null) and forwarded it anyway.","triggerScenarios":"Calling deadLetterJobQuery().scopeDefinitionId(null) directly, or calling caseDefinitionId(null) which delegates to scopeDefinitionId, with a null String, including inside an or() block.","commonSituations":"Resolving a definition id from a runtime CaseInstance/ProcessInstance that returned null; forwarding an optional variable or config value that was never set; refactoring code where a previously-set definition id became optional.","solutions":["Null-check the definition id before calling scopeDefinitionId and skip the filter (or fail fast with your own message) when it is absent.","Verify the upstream lookup (repositoryService/case service) that produced the id actually succeeded and the entity exists.","If the filter is optional, build the query conditionally: if (id != null) query.scopeDefinitionId(id)."],"exampleFix":"// before\nquery.scopeDefinitionId(caseInstance.getCaseDefinitionId());\n// after\nString defId = caseInstance.getCaseDefinitionId();\nif (defId != null) {\n    query.scopeDefinitionId(defId);\n}","handlingStrategy":"validation","validationCode":"if (scopeDefinitionId == null) { throw new IllegalStateException(\"scopeDefinitionId must be resolved before querying dead-letter jobs\"); }\nquery.scopeDefinitionId(scopeDefinitionId);","typeGuard":"boolean hasDefinitionId(String id) { return id != null && !id.isBlank(); }","tryCatchPattern":"try { query.scopeDefinitionId(id); } catch (FlowableIllegalArgumentException e) { log.warn(\"Invalid scopeDefinitionId: {}\", e.getMessage()); }","preventionTips":["Null-check every id obtained from runtime lookups before filtering","Make optional filters conditional instead of passing null","Fail fast with your own descriptive message when a required id is missing"],"tags":["flowable","query","null-check","validation"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}