apache/skywalking · error · RuntimeException

Illegal Service Relation entity id

Error message

Illegal Service Relation entity id

What it means

RuntimeException thrown by IDManager.ServiceID.analysisRelationId(String) when a service-relation entity id does not split into exactly 2 parts. Relation ids are built by buildRelationId as sourceServiceId + RELATION_ID_CONNECTOR + destServiceId; the decoder requires precisely two components and rejects anything else. Unlike the analysisId variants this throws bare RuntimeException, not UnexpectedException.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/IDManager.java:89

            return define.sourceId + Const.RELATION_ID_CONNECTOR + define.destId;
        }

        /**
         * @return encoded service hierarchy relation id
         */
        public static String buildServiceHierarchyRelationId(ServiceHierarchyRelationDefine define) {
            return define.serviceId + Const.SERVICE_ID_CONNECTOR + define.serviceLayer.value() +
                Const.RELATION_ID_CONNECTOR +
                define.relatedServiceId + Const.SERVICE_ID_CONNECTOR + define.relatedServiceLayer.value();
        }

        /**
         * @return service relation ID object decoded from {@link #buildRelationId(ServiceRelationDefine)} result
         */
        public static ServiceRelationDefine analysisRelationId(String entityId) {
            String[] parts = entityId.split(Const.RELATION_ID_PARSER_SPLIT);
            if (parts.length != 2) {
                throw new RuntimeException("Illegal Service Relation entity id");
            }
            return new ServiceRelationDefine(parts[0], parts[1]);
        }

        @RequiredArgsConstructor
        @Getter
        @EqualsAndHashCode
        public static class ServiceIDDefinition {
            private final String name;
            /**
             * TRUE means an agent installed or directly detected service. FALSE means a conjectural service
             */
            private final boolean isReal;
        }

        @RequiredArgsConstructor
        @Getter
        @EqualsAndHashCode

View on GitHub (pinned to 102af09b4a)

Solutions

1. Confirm the id came from ServiceID.buildRelationId(ServiceRelationDefine); hierarchy ids need their own parsing, not this method
2. Log and inspect the entity id from the message; count segments against the expected 2
3. If data corruption is suspected, check the source storage rows for the relation type involved
4. Guard call sites with a segment-count check before invoking analysisRelationId

Example fix

// before (hierarchy id fed to the wrong parser)
String id = IDManager.ServiceID.buildServiceHierarchyRelationId(def);
IDManager.ServiceID.analysisRelationId(id); // 4 segments -> throws

// after
String id = IDManager.ServiceID.buildRelationId(
    new ServiceRelationDefine(sourceSvcId, destSvcId));
IDManager.ServiceID.analysisRelationId(id); // 2 segments -> ok

if (entityId == null || entityId.split("\\.").length != 2) {
    throw new IllegalArgumentException("Not a plain service-relation id (use the hierarchy parser for 4-part ids): " + entityId);
}

boolean isPlainServiceRelationId(String id) {
    return id != null && id.split("\\.").length == 2;
}

try {
    ServiceRelationDefine def = IDManager.ServiceID.analysisRelationId(entityId);
} catch (RuntimeException e) {
    LOGGER.warn("Dropping malformed service relation entity id: {}", entityId, e);
}

When it happens

Trigger: Passing a service-hierarchy relation id (built by buildServiceHierarchyRelationId, which has 4 segments with layer values) into analysisRelationId by mistake; passing a hand-built string with 0, 1, or 3+ '.'-separated segments; passing null.

Common situations: Mixing up the two relation id formats after the service-hierarchy feature added buildServiceHierarchyRelationId; custom dashboards/queries joining ids with the wrong connector; corrupted storage rows.

Related errors

• Can't split service id into 2 parts, {}
• Can't split instance id into 2 parts, {}
• Illegal Service Instance Relation entity id
• Can't split endpoint id into 2 parts, {}
• Illegal endpoint Relation entity id, {}

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