pinpoint-apm/pinpoint · error · IllegalArgumentException

unknown TraceSourceType code

Error message

unknown TraceSourceType code:${code}

What it means

TraceSourceType.of maps a numeric code to one of the known TraceSourceType enum constants (currently PINPOINT and OPENTELEMETRY). Any other code has no mapping, so the factory throws this IllegalArgumentException to fail fast on unsupported trace source data.

Solutions

1. Upgrade the server/commons-server module so the enum knows the new code
2. Validate the source type code against supported values before decoding and skip unknown rows gracefully
3. Verify the deserialization offsets — a shifted byte stream can produce bogus codes

Example fix

// before
TraceSourceType type = TraceSourceType.of(code); // throws for unknown codes
// after
TraceSourceType type;
try {
    type = TraceSourceType.of(code);
} catch (IllegalArgumentException e) {
    logger.warn("Unknown trace source type " + code + ", defaulting to PINPOINT");
    type = TraceSourceType.PINPOINT;
}

TraceSourceType type = (code == TraceSourceType.PINPOINT.getCode())
    ? TraceSourceType.PINPOINT
    : (code == TraceSourceType.OPENTELEMETRY.getCode()) ? TraceSourceType.OPENTELEMETRY : null;
if (type == null) { /* skip or default */ }

TraceSourceType safeOf(int code) {
    try { return TraceSourceType.of(code); }
    catch (IllegalArgumentException e) { return null; }
}

try {
    type = TraceSourceType.of(code);
} catch (IllegalArgumentException e) {
    logger.warn("Unknown TraceSourceType code " + code + "; skipping or defaulting", e);
    type = TraceSourceType.PINPOINT;
}

When it happens

Trigger: Decoding trace data whose traceSourceType field holds a code not in {PINPOINT, OPENTELEMETRY} — e.g. data written by a newer agent/collector with an added source type, or garbage/corrupted bytes in that field.

Common situations: Forward compatibility gaps: server version older than the agent that introduced a new TraceSourceType code; manually edited or corrupted trace rows; wrong byte offsets during custom deserialization.

Related errors

• Unknown AgentType:
• unknown MethodType
• Unknown primaryForFieldAndTagRelation:
• Unknown SpanSenderType
• absolute start/end time is only supported for TRACE_V3 spans

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/625e198f60c4dd85. Report an issue: GitHub.

Appendix: source

Thrown at commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/TraceSourceType.java:48

    private final byte code;

    TraceSourceType(byte code) {
        this.code = code;
    }

    public byte getCode() {
        return this.code;
    }

    public static TraceSourceType of(byte code) {
        if (code == PINPOINT.code) {
            return PINPOINT;
        }
        if (code == OPENTELEMETRY.code) {
            return OPENTELEMETRY;
        }
        throw new IllegalArgumentException("unknown TraceSourceType code:" + code);
    }
}

View on GitHub (pinned to 744c3d3075)