pinpoint-apm/pinpoint · error · IllegalArgumentException

absolute start/end time is only supported for TRACE_V3 spans

Error message

absolute start/end time is only supported for TRACE_V3 spans

What it means

The absolute-time overload SpanBo.setTraceTime(version, startTime, endTime, elapsedMillis) is reserved exclusively for TRACE_V3 spans (epoch-nano start/end). Passing any other version throws IllegalArgumentException, keeping the two time representations mutually exclusive.

Solutions

1. Use the elapsed-only 3-arg setTraceTime for versions other than TRACE_V3
2. Branch on SpanVersion.TRACE_V3 before calling setTraceTime
3. Update readSpanValue/bind to select the overload by the row's version field
4. Fix hard-coded version constants in tests/migration code

Example fix

// before
span.setTraceTime(SpanVersion.TRACE_V2, start, end, elapsed); // throws
// after
if (version == SpanVersion.TRACE_V3) {
    span.setTraceTime(version, start, end, elapsed);
} else {
    span.setTraceTime(version, start, elapsed);
}

if (version != SpanVersion.TRACE_V3) { span.setTraceTime(version, startTime, elapsedMillis); } else { span.setTraceTime(version, startTime, endTime, elapsedMillis); }

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

try { span.setTraceTime(version, start, end, elapsed); } catch (IllegalArgumentException e) { log.warn("absolute time unsupported for version {}: {}", version, e.getMessage()); }

When it happens

Trigger: Calling the 4-arg setTraceTime for pre-V3 spans (version != TRACE_V3), e.g. passing TRACE_V2 or 0 because the data is legacy elapsed-based.

Common situations: Unified deserialization code that always calls the absolute-time overload regardless of version; converted legacy tests; copy-pasted bind logic.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• TRACE_V3 span requires absolute start/end time
• TRACE_V3 span end time is required
• list size not same
• span end time must be greater than or equal to start time
• unknown MethodType

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

Appendix: source

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

     */
    public void setTraceTime(int version, long startTime, int elapsedMillis) {
        if (version == SpanVersion.TRACE_V3) {
            throw new IllegalArgumentException("TRACE_V3 span requires absolute start/end time");
        }

        setVersion(version);
        this.startTime = startTime;
        this.elapsed = elapsedMillis;
        this.endTime = DEFAULT_END_TIME;
    }

    /**
     * Sets absolute span time for TRACE_V3 data.
     * startTime/endTime are epoch nanos. elapsedMillis is retained as the compatibility duration.
     */
    public void setTraceTime(int version, long startTime, long endTime, int elapsedMillis) {
        if (version != SpanVersion.TRACE_V3) {
            throw new IllegalArgumentException("absolute start/end time is only supported for TRACE_V3 spans");
        }
        if (endTime == DEFAULT_END_TIME) {
            throw new IllegalArgumentException("TRACE_V3 span end time is required");
        }
        if (endTime < startTime) {
            throw new IllegalArgumentException("span end time must be greater than or equal to start time");
        }

        setVersion(version);
        this.startTime = startTime;
        this.elapsed = elapsedMillis;
        this.endTime = endTime;
    }

    public boolean hasEndTime() {
        return endTime != DEFAULT_END_TIME;
    }

View on GitHub (pinned to 744c3d3075)