pinpoint-apm/pinpoint · error · IllegalArgumentException

TRACE_V3 span event requires absolute start/end time

Error message

TRACE_V3 span event requires absolute start/end time

What it means

This SpanEventBo.setTraceTime overload (startElapsedMillis/endElapsedMillis) is only valid for relative-time trace formats (TRACE_V2 and older). TRACE_V3 span events store absolute start/end nanos, so the method explicitly rejects TRACE_V3 because it would discard the absolute-time model.

Source

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

     */
    public int getEndElapsed() {
        return endElapsed;
    }

    public void setEndElapsed(int endElapsed) {
        this.endElapsed = endElapsed;
    }

    /**
     * Sets elapsed-only span event time for pre-V3 data.
     * startElapsedMillis is the offset from the parent span/chunk start, and endElapsedMillis
     * is the event duration.
     */
    public void setTraceTime(int version, int startElapsedMillis, int endElapsedMillis) {
        setVersion((byte) version);

        if (version == SpanVersion.TRACE_V3) {
            throw new IllegalArgumentException("TRACE_V3 span event requires absolute start/end time");
        }

        this.startTime = DEFAULT_START_TIME;
        this.endTime = DEFAULT_END_TIME;
        this.startElapsed = startElapsedMillis;
        this.endElapsed = endElapsedMillis;
    }

    /**
     * Sets absolute span event time for TRACE_V3 data.
     * startTime/endTime are epoch nanos. startElapsedMillis is retained as the compatibility
     * offset from the parent span/chunk start; endElapsedMillis is derived from endTime-startTime.
     */
    public void setTraceTime(int version, long startTime, long endTime, int startElapsedMillis) {
        setVersion((byte) version);

        if (version != SpanVersion.TRACE_V3) {
            throw new IllegalArgumentException("absolute start/end time is only supported for TRACE_V3 span events");

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Use the absolute-time overload setTraceTime(version, startTime, endTime, startElapsedMillis) for TRACE_V3 span events
  2. Check which decoder branch (V2 vs V3) is invoked in readSpanEvent and route V3 rows to the V3 path
  3. Ensure agent and collector/server versions agree on the trace format version

Example fix

// before
spanEventBo.setTraceTime(SpanVersion.TRACE_V3, startElapsed, endElapsed);
// after
spanEventBo.setTraceTime(SpanVersion.TRACE_V3, startNanos, endNanos, startElapsed);
Defensive patterns

Strategy: validation

Validate before calling

if (version != SpanVersion.TRACE_V3) {
    spanEventBo.setTraceTime(version, startElapsedMillis, endElapsedMillis);
} else {
    spanEventBo.setTraceTime(version, startNanos, endNanos, startElapsedMillis);
}

Type guard

boolean supportsRelativeElapsed(int version) {
    return version != SpanVersion.TRACE_V3;
}

Try / catch

try {
    spanEventBo.setTraceTime(version, startElapsed, endElapsed);
} catch (IllegalArgumentException e) {
    logger.warn("Relative time not allowed for version " + version, e);
}

Prevention

When it happens

Trigger: Calling setTraceTime(version, startElapsedMillis, endElapsedMillis) with version == SpanVersion.TRACE_V3, e.g. while decoding a span event via readSpanEvent or bind when the relative-elapsed decoder path is applied to V3 data.

Common situations: A decoder bug where the V2 relative-time path is chosen for V3-encoded rows; agents and servers at mismatched versions during a TRACE_V2 to TRACE_V3 migration; test code reusing the V2 setter for V3 objects.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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