apache/skywalking · error · IllegalArgumentException

queryAlarms entity is invalid (scope={scope}); required name

Error message

queryAlarms entity is invalid (scope={scope}); required name fields missing. Refusing to silently widen the filter to all alarms — see AlarmQueryCondition.entities documentation.

What it means

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.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/query/IAlarmQueryDAO.java:131

            if (entity.getScope() == null) {
                entity.setScope(inferScope(entity));
            }
            // Default `normal` flags to true when missing. The GraphQL Entity
            // input declares both nullable, but every scope that needs them
            // requires them per Entity.isValid(); defaulting to "normal
            // service" (agent-reporting, the common case) matches MQE-side
            // ergonomics and prevents the silent "all alarms" widening that
            // would happen if isValid() returned false and we skipped the
            // entry.
            if (entity.getScope() != null && entity.getNormal() == null) {
                entity.setNormal(Boolean.TRUE);
            }
            if (entity.getScope() != null && requiresDestNormal(entity.getScope())
                && entity.getDestNormal() == null) {
                entity.setDestNormal(Boolean.TRUE);
            }
            if (entity.getScope() == null || !entity.isValid()) {
                throw new IllegalArgumentException(
                    "queryAlarms entity is invalid (scope=" + entity.getScope()
                        + "); required name fields missing. Refusing to silently widen the "
                        + "filter to all alarms — see AlarmQueryCondition.entities documentation.");
            }
            switch (entity.getScope()) {
                case Service:
                case ServiceInstance:
                case Endpoint:
                case Process: {
                    final String id = entity.buildId();
                    constraints.add(new EntityIdConstraint(id, null));
                    constraints.add(new EntityIdConstraint(null, id));
                    break;
                }
                case ServiceRelation:
                    constraints.add(new EntityIdConstraint(
                        IDManager.ServiceID.buildId(entity.getServiceName(), entity.getNormal()),
                        IDManager.ServiceID.buildId(entity.getDestServiceName(), entity.getDestNormal())));

View on GitHub (pinned to 102af09b4a)

Solutions

1. Set 'scope' on every entity and fill the name fields that scope requires (Service → serviceName; ServiceInstance → serviceName+serviceInstance; Endpoint → serviceName+endpointName; Process adds processName).
2. 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.
3. Consult the AlarmQueryCondition.entities documentation referenced in the message for the exact per-scope field matrix.

Example fix

# GraphQL — before
entities: [{ scope: Service }]  # no serviceName

# after
entities: [{ scope: Service, serviceName: "my-service", normal: true }]

// Client-side entity validation mirroring the server rule
for (AlarmQueryCondition.Entity e : condition.getEntities()) {
    require(e.getScope() != null, "scope required");
    require(isNotBlank(e.getServiceName()), "serviceName required");
    if (e.getScope() == Scope.ServiceInstance) require(isNotBlank(e.getServiceInstance()), "instance name required");
    if (e.getScope() == Scope.Endpoint) require(isNotBlank(e.getEndpointName()), "endpoint name required");
}

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; } }

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; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• time field is required when uuid is absent.
• line {}:{} {}
• Duration data error, the range between the start time and th
• End time must not be before start
• Failed to load GenAI configuration file.

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/b5792b8cde7c1bcc. Report an issue: GitHub.