{"record":{"id":"d0d5378ebe6a113e","repo":"flowable/flowable-engine","slug":"cannot-use-subscopeid-together-with-excludelocalva-d0d537","errorCode":null,"errorMessage":"Cannot use subScopeId together with excludeLocalVariables","messagePattern":"Cannot use subScopeId together with excludeLocalVariables","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/VariableInstanceQueryImpl.java","lineNumber":248,"sourceCode":"    @Override\n    public VariableInstanceQuery variableNameLike(String variableNameLike) {\n        if (variableNameLike == null) {\n            throw new FlowableIllegalArgumentException(\"variableNameLike is null\");\n        }\n        this.variableNameLike = variableNameLike;\n        return this;\n    }\n    \n    @Override\n    public VariableInstanceQuery scopeId(String scopeId) {\n        this.scopeId = scopeId;\n        return this;\n    }\n    \n    @Override\n    public VariableInstanceQuery subScopeId(String subScopeId) {\n        if (excludeLocalVariables) {\n            throw new FlowableIllegalArgumentException(\"Cannot use subScopeId together with excludeLocalVariables\");\n        }\n        this.subScopeId = subScopeId;\n        return this;\n    }\n    \n    @Override\n    public VariableInstanceQuery scopeType(String scopeType) {\n        this.scopeType = scopeType;\n        return this;\n    }\n\n    @Override\n    public VariableInstanceQuery excludeLocalVariables() {\n        if (taskId != null) {\n            throw new FlowableIllegalArgumentException(\"Cannot use taskId together with excludeLocalVariables\");\n        }\n        if (taskIds != null) {\n            throw new FlowableIllegalArgumentException(\"Cannot use taskIds together with excludeLocalVariables\");","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/VariableInstanceQueryImpl.java#L230-L266","documentation":"Flowable throws FlowableIllegalArgumentException when subScopeId(...) is called on a VariableInstanceQuery that already has excludeLocalVariables enabled. The two options are mutually exclusive: excludeLocalVariables changes the query semantics in a way that cannot be combined with sub-scope filtering, so the builder refuses the combination at call time.","triggerScenarios":"Calling query.excludeLocalVariables().subScopeId(\"someSubScopeId\") in either order (subScopeId after excludeLocalVariables triggers this message); shared query-builder code that always enables exclusion then optionally adds a subScopeId.","commonSituations":"Refactors that added excludeLocalVariables to a base query while other call sites still pass a subScopeId; copy-pasted query setup that mixes variable-scoping strategies.","solutions":["Remove one of the two conflicting options: drop the subScopeId call or drop excludeLocalVariables()","Choose the scoping strategy explicitly — if you need sub-scope filtering, do not exclude local variables","Build two alternative queries depending on whether a subScopeId is present"],"exampleFix":"// before\nquery.excludeLocalVariables();\nquery.subScopeId(subScopeId); // throws\n// after\nquery.subScopeId(subScopeId); // pick one strategy\n// or, without subScopeId:\nquery.excludeLocalVariables();","handlingStrategy":"validation","validationCode":"if (subScopeId != null && excludeLocal) {\n    throw new IllegalArgumentException(\"subScopeId cannot be combined with excludeLocalVariables\");\n}\nquery.subScopeId(subScopeId);","typeGuard":null,"tryCatchPattern":"try {\n    query.excludeLocalVariables().subScopeId(subScopeId);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"subScopeId together with excludeLocalVariables\")) {\n        // rebuild the query with only one of the two options\n        query = variableInstanceQueryService.createVariableInstanceQuery().subScopeId(subScopeId);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Know the mutual-exclusion rules of VariableInstanceQuery before composing fluent chains","Build queries in one place so conflicting options cannot be combined","Check previously-set options before calling scoping methods"],"tags":["query","conflicting-options","validation","flowable"],"backgroundTag":"mutually-exclusive-options","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"}