apache/skywalking · error · UnexpectedException

Illegal endpoint Relation entity id, {}

Error message

Illegal endpoint Relation entity id, {}

What it means

UnexpectedException thrown by IDManager.EndpointID.analysisRelationId(String) when an endpoint-relation entity id does not split into exactly 4 parts by Const.RELATION_ID_PARSER_SPLIT. The format from buildRelationId is sourceServiceId + '.' + encode(sourceEndpoint) + '.' + destServiceId + '.' + encode(destEndpoint); the decoder demands exactly four components and includes the bad id in the message.

Source

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

         * @return the endpoint relationship string id.
         */
        public static String buildRelationId(EndpointRelationDefine define) {
            return define.sourceServiceId
                + Const.RELATION_ID_CONNECTOR
                + encode(define.source)
                + Const.RELATION_ID_CONNECTOR
                + define.destServiceId
                + Const.RELATION_ID_CONNECTOR
                + encode(define.dest);
        }

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

        @RequiredArgsConstructor
        @Getter
        public static class EndpointIDDefinition {
            /**
             * Built by {@link ServiceID#buildId(String, boolean)}
             */
            private final String serviceId;
            private final String endpointName;
        }

View on GitHub (pinned to 102af09b4a)

Solutions

1. Ensure only ids from EndpointID.buildRelationId(EndpointRelationDefine) reach this method; route service/instance relation ids to their own analysisRelationId variants
2. Verify both endpoint names went through encode() when the id was written
3. Inspect the failing id from the message and count segments to identify the producer
4. Clean or reindex malformed stored relation rows

Example fix

// before (wrong parser for a service relation id)
EndpointID.analysisRelationId(serviceRelationEntityId); // 2 parts -> throws

// after
ServiceID.analysisRelationId(serviceRelationEntityId); // 2-part parser
EndpointID.analysisRelationId(endpointRelationEntityId); // 4-part parser

int parts = entityId == null ? 0 : entityId.split("\\.").length;
if (parts != 4) {
    throw new IllegalArgumentException("Not an endpoint-relation id (expected 4 parts, got " + parts + "): " + entityId);
}

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

try {
    EndpointRelationDefine def = IDManager.EndpointID.analysisRelationId(entityId);
} catch (UnexpectedException e) {
    LOGGER.warn("Dropping malformed endpoint relation id: {}", entityId, e);
}

When it happens

Trigger: Passing a 2-segment relation id (service-level or instance-level relation) into the endpoint parser; endpoint names not URL-encoded by the producer so embedded separators change the segment count; truncated or corrupted entity ids from storage; null input.

Common situations: Polymorphic handling of relation ids in query/aggregation code that routes all relations to one parser; custom fetchers or exporters re-building relation ids; upgrades where encoding of endpoint names changed, leaving legacy 3- or 5-segment rows.

Related errors

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

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