{"record":{"id":"b5792b8cde7c1bcc","repo":"apache/skywalking","slug":"queryalarms-entity-is-invalid-scope-scope-req","errorCode":null,"errorMessage":"queryAlarms entity is invalid (scope={scope}); required name fields missing. Refusing to silently widen the filter to all alarms — see AlarmQueryCondition.entities documentation.","messagePattern":"queryAlarms entity is invalid \\(scope=(.+?)\\); required name fields missing\\. Refusing to silently widen the filter to all alarms — see AlarmQueryCondition\\.entities documentation\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/query/IAlarmQueryDAO.java","lineNumber":131,"sourceCode":"            if (entity.getScope() == null) {\n                entity.setScope(inferScope(entity));\n            }\n            // Default `normal` flags to true when missing. The GraphQL Entity\n            // input declares both nullable, but every scope that needs them\n            // requires them per Entity.isValid(); defaulting to \"normal\n            // service\" (agent-reporting, the common case) matches MQE-side\n            // ergonomics and prevents the silent \"all alarms\" widening that\n            // would happen if isValid() returned false and we skipped the\n            // entry.\n            if (entity.getScope() != null && entity.getNormal() == null) {\n                entity.setNormal(Boolean.TRUE);\n            }\n            if (entity.getScope() != null && requiresDestNormal(entity.getScope())\n                && entity.getDestNormal() == null) {\n                entity.setDestNormal(Boolean.TRUE);\n            }\n            if (entity.getScope() == null || !entity.isValid()) {\n                throw new IllegalArgumentException(\n                    \"queryAlarms entity is invalid (scope=\" + entity.getScope()\n                        + \"); required name fields missing. Refusing to silently widen the \"\n                        + \"filter to all alarms — see AlarmQueryCondition.entities documentation.\");\n            }\n            switch (entity.getScope()) {\n                case Service:\n                case ServiceInstance:\n                case Endpoint:\n                case Process: {\n                    final String id = entity.buildId();\n                    constraints.add(new EntityIdConstraint(id, null));\n                    constraints.add(new EntityIdConstraint(null, id));\n                    break;\n                }\n                case ServiceRelation:\n                    constraints.add(new EntityIdConstraint(\n                        IDManager.ServiceID.buildId(entity.getServiceName(), entity.getNormal()),\n                        IDManager.ServiceID.buildId(entity.getDestServiceName(), entity.getDestNormal())));","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/query/IAlarmQueryDAO.java#L113-L149","documentation":"IAlarmQueryDAO.queryAlarms validates each AlarmQueryCondition.entities entry before translating it into storage constraints. An entity must have a scope AND pass isValid() (the required name fields for that scope, e.g. serviceName for Service, plus instance/endpoint names for finer scopes). The code auto-fills 'normal' flags when scope is set, but an entity with null scope or missing name fields is rejected outright — the service deliberately refuses to drop the filter and return all alarms, since that would be a silent privilege/scope escalation.","triggerScenarios":"Calling the alarms GraphQL/API with an entities entry whose 'scope' is null, or whose scope is set but required name fields (serviceName/serviceInstance/endpointName per scope) are missing.","commonSituations":"UI alarm filters built from partial context (scope selected, entity name not yet resolved); API clients copying an entity template and only setting scope; scripts filtering by 'normal' flag alone without naming an entity.","solutions":["Set 'scope' on every entity and fill the name fields that scope requires (Service → serviceName; ServiceInstance → serviceName+serviceInstance; Endpoint → serviceName+endpointName; Process adds processName).","If you truly want all alarms, omit the entities filter entirely rather than sending an empty entity — the widening is only refused when a malformed entity is present.","Consult the AlarmQueryCondition.entities documentation referenced in the message for the exact per-scope field matrix."],"exampleFix":"# GraphQL — before\nentities: [{ scope: Service }]  # no serviceName\n\n# after\nentities: [{ scope: Service, serviceName: \"my-service\", normal: true }]","handlingStrategy":"validation","validationCode":"// Client-side entity validation mirroring the server rule\nfor (AlarmQueryCondition.Entity e : condition.getEntities()) {\n    require(e.getScope() != null, \"scope required\");\n    require(isNotBlank(e.getServiceName()), \"serviceName required\");\n    if (e.getScope() == Scope.ServiceInstance) require(isNotBlank(e.getServiceInstance()), \"instance name required\");\n    if (e.getScope() == Scope.Endpoint) require(isNotBlank(e.getEndpointName()), \"endpoint name required\");\n}","typeGuard":"boolean isAlarmEntityValid(Entity e) { if (e.getScope() == null) return false; switch (e.getScope()) { case Service: return isNotBlank(e.getServiceName()); case ServiceInstance: return isNotBlank(e.getServiceName()) && isNotBlank(e.getServiceInstance()); case Endpoint: return isNotBlank(e.getServiceName()) && isNotBlank(e.getEndpointName()); case Process: return isNotBlank(e.getServiceName()) && isNotBlank(e.getProcessName()); default: return false; } }","tryCatchPattern":"try { alarms = alarmQueryDAO.queryAlarms(...); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"required name fields missing\")) { /* fix entities client-side; never retry unfiltered */ throw new BadRequest(\"invalid alarm entity filter\", e); } throw e; }","preventionTips":["Build entity filters via typed factory methods per scope that enforce required fields.","Never send a scope-only entity; omit 'entities' entirely when no filter is intended.","Read the AlarmQueryCondition.entities docs for the per-scope field matrix and mirror it in client models."],"tags":["query","alarms","validation","graphql","api-contract"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}