{"record":{"id":"932e03ba7f29647a","repo":"flowable/flowable-engine","slug":"cannot-use-subscopeid-together-with-excludelocalva","errorCode":null,"errorMessage":"Cannot use subScopeId together with excludeLocalVariables","messagePattern":"Cannot use subScopeId together with excludeLocalVariables","errorType":"validation","errorClass":"org.flowable.common.engine.api.FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/HistoricVariableInstanceQueryImpl.java","lineNumber":269,"sourceCode":"    @Override\n    public HistoricVariableInstanceQuery scopeId(String scopeId) {\n        this.scopeId = scopeId;\n        return this;\n    }\n    \n    @Override\n    public HistoricVariableInstanceQuery scopeIds(Collection<String> scopeIds) {\n        if (scopeIds == null || scopeIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"scopeIds is empty\");\n        }\n        this.scopeIds = scopeIds;\n        return this;\n    }\n\n    @Override\n    public HistoricVariableInstanceQuery subScopeId(String subScopeId) {\n        if (excludeLocalVariables) {\n            throw new FlowableIllegalArgumentException(\"Cannot use subScopeId together with excludeLocalVariables\");\n        }\n\n        this.subScopeId = subScopeId;\n        return this;\n    }\n    \n    @Override\n    public HistoricVariableInstanceQuery scopeType(String scopeType) {\n        this.scopeType = scopeType;\n        return this;\n    }\n\n    @Override\n    public HistoricVariableInstanceQuery excludeLocalVariables() {\n        if (taskId != null) {\n            throw new FlowableIllegalArgumentException(\"Cannot use taskId together with excludeLocalVariables\");\n        }\n        if (taskIds != null) {","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/HistoricVariableInstanceQueryImpl.java#L251-L287","documentation":"HistoricVariableInstanceQuery.subScopeId() throws FlowableIllegalArgumentException when excludeLocalVariables was already enabled on the query. Sub-scope filtering is a local-variable-oriented concept and is mutually exclusive with excluding local variables, so combining them is an invalid query state the library refuses to build.","triggerScenarios":"Calling query.excludeLocalVariables() followed by query.subScopeId(\"...\") — in any order, since subScopeId checks the excludeLocalVariables flag which excludeLocalVariables() sets; the flag is already true when subScopeId is invoked.","commonSituations":"Building a shared query configurator that always calls excludeLocalVariables() and then conditionally adds subScopeId; copying query options from another query that had excludeLocalVariables set.","solutions":["Remove the excludeLocalVariables() call when filtering by subScopeId.","Choose one filtering strategy: either subScopeId-based local variable lookup or excludeLocalVariables.","If both options can be requested by callers, validate and reject the combination in your own code with a clear message.","If a scope/task id is known, consider taskId/executionId filters, which also conflict with excludeLocalVariables."],"exampleFix":"// before\nquery.excludeLocalVariables().subScopeId(\"mySubScope\");\n\n// after\nquery.subScopeId(\"mySubScope\"); // drop excludeLocalVariables","handlingStrategy":"validation","validationCode":"if (useExcludeLocalVariables && subScopeId != null) {\n    throw new IllegalArgumentException(\"excludeLocalVariables cannot be combined with subScopeId\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    query.subScopeId(subScopeId);\n} catch (FlowableIllegalArgumentException e) {\n    throw new IllegalStateException(\"Query configured with excludeLocalVariables; subScopeId not allowed\", e);\n}","preventionTips":["Never call excludeLocalVariables() unconditionally in shared query-building code.","Keep task/execution/subScope-scoped query builders separate from exclusion-based ones.","Document and enforce flag combinations in your own query configuration layer."],"tags":["flowable","query","conflicting-options","validation"],"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"}