{"record":{"id":"5f5fc633b58836d2","repo":"flowable/flowable-engine","slug":"provided-scope-id-is-null-5f5fc6","errorCode":null,"errorMessage":"Provided scope id is null","messagePattern":"Provided scope id 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":239,"sourceCode":"    }\n    \n    @Override\n    public DeadLetterJobQueryImpl elementName(String elementName) {\n        if (elementName == null) {\n            throw new FlowableIllegalArgumentException(\"Provided element name is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.elementName = elementName;\n        } else {\n            this.elementName = elementName;\n        }\n        return this;\n    }\n    \n    @Override\n    public DeadLetterJobQueryImpl scopeId(String scopeId) {\n        if (scopeId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided scope id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.scopeId = scopeId;\n        } else {\n            this.scopeId = scopeId;\n        }\n        return this;\n    }\n\n    @Override\n    public DeadLetterJobQuery scopeIds(Collection<String> scopeIds) {\n        if (scopeIds == null) {\n            throw new FlowableIllegalArgumentException(\"Provided scope ids are null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.scopeIds = scopeIds;\n        } else {\n            this.scopeIds = scopeIds;","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/DeadLetterJobQueryImpl.java#L221-L257","documentation":"DeadLetterJobQueryImpl.scopeId() throws FlowableIllegalArgumentException when the scopeId parameter is null. scopeId identifies the owning scope (process, case, etc.) of the jobs. Note that convenience wrappers such as caseInstanceId() delegate to scopeId (often together with scopeType), so a null case instance id can surface as this scopeId error.","triggerScenarios":"Calling deadLetterJobQuery().scopeId(null), or caseInstanceId(null) which delegates to scopeId and triggers this check; passing a scope id read from an entity or message whose field was not populated.","commonSituations":"CMMN/case integrations querying jobs for a case instance whose id variable is null because the case was never started or the lookup failed; generic scope-handling code that passes through whatever id it received without a null guard.","solutions":["Null-check the id (or the wrapped caseInstanceId) before calling scopeId(...)","Omit the scope filter to query dead-letter jobs across all scopes","When using caseInstanceId(...), remember it also sets scopeType - pass a non-null id or skip both","Trace why the scope id is missing (entity not persisted, wrong variable name, failed lookup)"],"exampleFix":"// before\nquery.caseInstanceId(caseInstanceId); // throws here when null\n\n// after\nDeadLetterJobQuery query = jobService.createDeadLetterJobQuery();\nif (caseInstanceId != null) {\n    query = query.caseInstanceId(caseInstanceId);\n}","handlingStrategy":"validation","validationCode":"if (scopeId != null) {\n    query = query.scopeId(scopeId);\n}","typeGuard":"boolean hasScopeId(EntityWithScope e) { return e != null && e.getScopeId() != null; }","tryCatchPattern":"try {\n    return query.caseInstanceId(caseInstanceId).list();\n} catch (FlowableIllegalArgumentException e) {\n    throw new InvalidQueryRequestException(\"scope/case instance id must not be null\", e);\n}","preventionTips":["Guard wrapper methods (caseInstanceId) the same as direct scopeId calls - they delegate to the same check","Verify the entity or variable that supplied the scope id was actually populated","Omit the scope filter when no scope is targeted","Keep scopeId and scopeType assignments paired and null-checked together"],"tags":["flowable","null-argument","query-builder","scope"],"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"}