{"record":{"id":"597369b7926925f8","repo":"flowable/flowable-engine","slug":"provided-sub-scope-id-is-null-597369","errorCode":null,"errorMessage":"Provided sub scope id is null","messagePattern":"Provided sub scope id is null","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java","lineNumber":276,"sourceCode":"            this.scopeIds = scopeIds;\n        }\n        return this;\n    }\n    \n    @Override\n    public ExternalWorkerJobQuery withoutScopeId() {\n        if (inOrStatement) {\n            this.currentOrQueryObject.withoutScopeId = true;\n        } else {\n            this.withoutScopeId = true;\n        }\n        return this;\n    }\n\n    @Override\n    public ExternalWorkerJobQuery subScopeId(String subScopeId) {\n        if (subScopeId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided sub scope id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.subScopeId = subScopeId;\n        } else {\n            this.subScopeId = subScopeId;\n        }\n        return this;\n    }\n\n    @Override\n    public ExternalWorkerJobQueryImpl scopeType(String scopeType) {\n        if (scopeType == null) {\n            throw new FlowableIllegalArgumentException(\"Provided scope type is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.scopeType = scopeType;\n        } else {\n            this.scopeType = scopeType;","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java#L258-L294","documentation":"ExternalWorkerJobQueryImpl.subScopeId() rejects a null sub-scope id. The sub-scope id identifies the finer-grained entity (such as a plan item instance) within a scope; a null value would make the filter meaningless, so Flowable throws FlowableIllegalArgumentException immediately. This method is also the target of planItemInstanceId(), which forwards its argument here.","triggerScenarios":"Calling externalWorkerJobQuery.subScopeId(null) directly, or calling planItemInstanceId(null) which delegates to subScopeId, including inside an or() block.","commonSituations":"Chaining case/plan-item filters built from optional variables; passing an uninitialized field or a null result of a lookup into planItemInstanceId.","solutions":["Pass a non-null sub scope id; skip the filter call when the value is null","Wrap the value in Objects.requireNonNull checks at your query-builder layer","Fix upstream lookups that return null (e.g. missing plan item instance)","Catch FlowableIllegalArgumentException around query construction"],"exampleFix":"// before\nquery.planItemInstanceId(planItem.getId()); // planItem can be null\n// after\nif (planItem != null) {\n    query.planItemInstanceId(planItem.getId());\n}","handlingStrategy":"validation","validationCode":"if (subScopeId == null) { throw new IllegalArgumentException(\"subScopeId must not be null\"); }\nquery.subScopeId(subScopeId);","typeGuard":"boolean hasSubScopeId(String subScopeId) { return subScopeId != null && !subScopeId.trim().isEmpty(); }","tryCatchPattern":"try {\n    query.subScopeId(subScopeId);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Null sub scope id in job query: {}\", e.getMessage());\n    throw new InvalidQueryException(e);\n}","preventionTips":["Validate ids from upstream lookups before using them in query filters","Remember planItemInstanceId() delegates to subScopeId() — a null plan item id triggers this error too","Keep query construction in one place so null guards are not duplicated","Prefer Optional<String> at your API boundary and unwrap explicitly"],"tags":["flowable","null-check","query","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-18T11:17:12.947Z"}