apache/skywalking · error · RuntimeException

Illegal Process Relation entity id

Error message

Illegal Process Relation entity id

What it means

RuntimeException thrown by IDManager.ProcessID.analysisRelationId(String) when a process-relation entity id does not split into exactly 2 parts. Process relation ids are produced by buildRelationId as sourceProcessId + RELATION_ID_CONNECTOR + destProcessId; the strict two-part decoder rejects everything else (bare RuntimeException, and note the id is not included in the message).

Source

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

            return Hashing.sha256().newHasher().putString(String.format("%s_%s",
                                                                        name, instanceId
            ), Charsets.UTF_8).hash().toString();
        }

        /**
         * @return encoded process relation id
         */
        public static String buildRelationId(ProcessRelationDefine define) {
            return define.sourceId + Const.RELATION_ID_CONNECTOR + define.destId;
        }

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

        @RequiredArgsConstructor
        @Getter
        @EqualsAndHashCode
        public static class ProcessRelationDefine {
            private final String sourceId;
            private final String destId;
        }
    }

    /**
     * Network Address Alias ID related functions.
     */
    public static class NetworkAddressAliasDefine {
        /**

View on GitHub (pinned to 102af09b4a)

Solutions

1. Generate ids only via ProcessID.buildRelationId(ProcessRelationDefine) and decode only its output
2. At call sites, check entityId.split(REGEX).length == 2 (or wrap in try/catch) before decoding, since the message lacks the id
3. Log the raw entityId at the call site on failure to identify the producer
4. Repair or drop malformed relation rows in storage

Example fix

// before
ProcessID.analysisRelationId(processId); // single id -> throws

// after
String relId = IDManager.ProcessID.buildRelationId(
    new ProcessRelationDefine(sourceProcId, destProcId));
IDManager.ProcessID.analysisRelationId(relId);

if (entityId == null || entityId.split("\\.").length != 2) {
    throw new IllegalArgumentException("Not a process-relation id: " + entityId);
}

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

try {
    ProcessRelationDefine def = IDManager.ProcessID.analysisRelationId(entityId);
} catch (RuntimeException e) {
    LOGGER.warn("Dropping malformed process relation id: {}", entityId, e);
}

When it happens

Trigger: Passing a hand-built process relation string with the wrong connector, a single process id, an id with 3+ segments, or null into analysisRelationId; corrupted rows from storage deserialization.

Common situations: Custom profiling or process-level analysis code constructing relation ids manually; tests with fabricated ids; storage rows damaged by partial writes or encoding migrations.

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/a28f3ad309744721. Report an issue: GitHub.