pinpoint-apm/pinpoint · error · IllegalArgumentException

absolute start/end time is only supported for TRACE_V3 span

Error message

absolute start/end time is only supported for TRACE_V3 span events

What it means

This SpanEventBo.setTraceTime overload (startTime/endTime/startElapsedMillis) exists specifically for TRACE_V3, which encodes absolute epoch-nano start/end times. Passing any other version is rejected because older formats cannot represent absolute nanosecond timestamps.

Source

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

            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");
        }
        if (endTime < startTime) {
            throw new IllegalArgumentException("span event end time must be greater than or equal to start time");
        }

        this.startTime = startTime;
        this.endTime = endTime;
        this.startElapsed = startElapsedMillis;
        this.endElapsed = (int) TimeUnit.NANOSECONDS.toMillis(endTime - startTime);
    }

    public boolean hasStartTime() {
        return Byte.toUnsignedInt(version) == SpanVersion.TRACE_V3 && startTime != DEFAULT_START_TIME;
    }

    public long getStartTimeNanos() {
        if (!hasStartTime()) {
            throw new IllegalStateException("span event start time is not set");

View on GitHub (pinned to 744c3d3075)

Solutions

Only call the absolute-time overload when version == SpanVersion.TRACE_V3; otherwise use the relative-elapsed overload
Fix the decoder branch in readSpanEvent so V2 rows take the elapsed-millis path
Correct the version byte on the data being decoded if it was mislabeled

Example fix

// before
spanEventBo.setTraceTime(SpanVersion.TRACE_V2, startNanos, endNanos, elapsed);
// after
if (version == SpanVersion.TRACE_V3) {
    spanEventBo.setTraceTime(version, startNanos, endNanos, elapsed);
} else {
    spanEventBo.setTraceTime(version, startElapsed, endElapsed);
}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
    spanEventBo.setTraceTime(version, startNanos, endNanos, elapsed);
} catch (IllegalArgumentException e) {
    logger.warn("Absolute time setter used with version " + version, e);
}

Prevention

Only construct V3 events with start/end absolute nanos
Keep version byte assignment and time setter choice adjacent in code
Cover mixed-version data in deserialization tests

When it happens

Trigger: Calling setTraceTime(version, startTime, endTime, startElapsedMillis) with a version other than SpanVersion.TRACE_V3, typically from the readSpanEvent/bind decode path when the absolute-time constructor is applied to V2 or unknown-version data.

Common situations: Applying the V3 absolute-time setter to V2 rows during mixed-version batch reads; migration scripts converting old data but stamping the wrong version byte; tests constructing V2 events with the V3 API.

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