pinpoint-apm/pinpoint · error · IllegalArgumentException

TRACE_V3 span end time is required

Error message

TRACE_V3 span end time is required

What it means

For TRACE_V3 spans, endTime is mandatory: a value equal to DEFAULT_END_TIME (the unset sentinel used by pre-V3 spans) is rejected with IllegalArgumentException. V3 stores absolute times, so an unset end time would leave the span interval undefined.

Solutions

  1. Provide a real epoch-nano endTime (e.g. startTime + elapsedMillis converted to nanos) when constructing V3 spans
  2. Ensure the deserializer reads the persisted end-time field before calling setTraceTime
  3. Compute endTime from startTime if the source stores only a duration
  4. Update span-construction helpers to require endTime for V3

Example fix

// before
span.setTraceTime(SpanVersion.TRACE_V3, startTime, SpanBo.DEFAULT_END_TIME, elapsed); // throws
// after
long endTime = startTime + TimeUnit.MILLISECONDS.toNanos(elapsed);
span.setTraceTime(SpanVersion.TRACE_V3, startTime, endTime, elapsed);
Defensive patterns

Strategy: validation

Validate before calling

if (version == SpanVersion.TRACE_V3 && endTime == SpanBo.DEFAULT_END_TIME) { endTime = startTime + TimeUnit.MILLISECONDS.toNanos(elapsedMillis); }

Type guard

boolean hasEndTime(long endTime) { return endTime != SpanBo.DEFAULT_END_TIME && endTime > 0; }

Try / catch

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

Prevention

When it happens

Trigger: Calling setTraceTime(version, startTime, endTime, elapsedMillis) with version == TRACE_V3 while endTime is still DEFAULT_END_TIME — i.e. the caller never resolved a real end timestamp.

Common situations: Converted pre-V3 code paths that leave endTime at its default sentinel; partially migrated deserializers that populate start but not end; tests constructing minimal V3 spans without an end time.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

            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;
    }

    public long getEndTimeMillis() {
        if (hasEndTime()) {
            return timeAccessor().toMillis(endTime);

View on GitHub (pinned to 744c3d3075)