{"record":{"id":"024e69f95ae2dd69","repo":"flowable/flowable-engine","slug":"provided-scope-definition-id-is-null","errorCode":null,"errorMessage":"Provided scope definition id is null","messagePattern":"Provided scope definition id is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-eventsubscription-service/src/main/java/org/flowable/eventsubscription/service/impl/EventSubscriptionQueryImpl.java","lineNumber":308,"sourceCode":"\n        return this;\n    }\n    \n    @Override\n    public EventSubscriptionQueryImpl withoutScopeId() {\n        if (inOrStatement) {\n            this.currentOrQueryObject.withoutScopeId = true;\n        } else {\n            this.withoutScopeId = true;\n        }\n\n        return this;\n    }\n    \n    @Override\n    public EventSubscriptionQueryImpl scopeDefinitionId(String scopeDefinitionId) {\n        if (scopeDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided scope definition id is null\");\n        }\n\n        if (inOrStatement) {\n            this.currentOrQueryObject.scopeDefinitionId = scopeDefinitionId;\n        } else {\n            this.scopeDefinitionId = scopeDefinitionId;\n        }\n\n        return this;\n    }\n    \n    @Override\n    public EventSubscriptionQueryImpl withoutScopeDefinitionId() {\n        if (inOrStatement) {\n            this.currentOrQueryObject.withoutScopeDefinitionId = true;\n        } else {\n            this.withoutScopeDefinitionId = true;\n        }","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-eventsubscription-service/src/main/java/org/flowable/eventsubscription/service/impl/EventSubscriptionQueryImpl.java#L290-L326","documentation":"Flowable throws FlowableIllegalArgumentException from EventSubscriptionQueryImpl.scopeDefinitionId when scopeDefinitionId() is called with null. This filter narrows subscriptions to a specific process or case definition id and null is rejected at build time. Provide a non-null definition id or skip the filter.","triggerScenarios":"Calling .scopeDefinitionId(null), typically when the definition id was not resolved (missing deployment) or when shared code passes whichever definition id variable happens to be null for the current scope type.","commonSituations":"Definition lookup by key returned no result; BPMN/CMMN shared helpers where only one of processDefinitionId/caseDefinitionId is set; confusing scopeDefinitionId with scopeId.","solutions":["Null-check the definition id before applying the filter","Resolve the definition id first (process or case definition query) and confirm it exists","Omit the filter when no definition constraint is needed","Verify you are passing the definition id, not the instance/scope id"],"exampleFix":"// before\nquery.scopeDefinitionId(defId);\n\n// after\nif (defId != null) {\n    query.scopeDefinitionId(defId);\n}","handlingStrategy":"validation","validationCode":"if (scopeDefinitionId == null) {\n    throw new IllegalStateException(\"scopeDefinitionId required\");\n}\nquery.scopeDefinitionId(scopeDefinitionId);","typeGuard":"if (id instanceof String && !((String) id).isEmpty()) { /* safe to filter */ }","tryCatchPattern":"try {\n    query.scopeDefinitionId(defId).list();\n} catch (FlowableIllegalArgumentException e) {\n    // definition id unresolved\n}","preventionTips":["Resolve the definition id for the active scope type first","Null-check before filtering","Do not confuse scopeDefinitionId with scopeId"],"tags":["flowable","null-check","query-builder","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"}