pinpoint-apm/pinpoint · error · IllegalArgumentException

span chunk keyTime is only supported for TRACE_V2 or TRACE_V

Error message

span chunk keyTime is only supported for TRACE_V2 or TRACE_V3

What it means

SpanChunkBo.setTraceTime sets span chunk time fields as one versioned unit and only accepts TRACE_V2 (epoch millis) or TRACE_V3 (epoch nanos) trace formats. If any other version value is passed, the constructor rejects it with this IllegalArgumentException because time encoding is undefined for older or unknown versions.

Source

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

    private TraceTimeAccessor timeAccessor() {
        return TraceTimeAccessor.ofVersion(this.version);
    }

    public long getKeyTimeMillis() {
        return timeAccessor().toMillis(keyTime);
    }

    public long getKeyTimeNanos() {
        return timeAccessor().toNanos(keyTime);
    }

    /**
     * Sets the span chunk time fields as one versioned unit.
     * TRACE_V2 uses epoch millis. TRACE_V3 uses epoch nanos.
     */
    public void setTraceTime(int version, long keyTime) {
        if (version != SpanVersion.TRACE_V2 && version != SpanVersion.TRACE_V3) {
            throw new IllegalArgumentException("span chunk keyTime is only supported for TRACE_V2 or TRACE_V3");
        }
        setVersion(version);
        this.keyTime = keyTime;
    }

    public String getEndPoint() {
        return endPoint;
    }

    public void setEndPoint(String endPoint) {
        this.endPoint = endPoint;
    }

    @Override
    public long getCollectorAcceptTime() {
        return collectorAcceptTime;
    }

View on GitHub (pinned to 744c3d3075)

Solutions

Verify the trace version of the data being deserialized is TRACE_V2 or TRACE_V3 before calling setTraceTime
Check the agent version that produced the span chunk data; upgrade or re-map data to a supported trace version
Log and skip/move malformed rows instead of letting the deserializer throw, if the data source may contain legacy rows

Example fix

// before
spanChunkBo.setTraceTime(unknownVersion, keyTime);
// after
if (version == SpanVersion.TRACE_V2 || version == SpanVersion.TRACE_V3) {
    spanChunkBo.setTraceTime(version, keyTime);
} else {
    logger.warn("Unsupported span chunk trace version: " + version);
}

Defensive patterns

Strategy: validation

Validate before calling

if (version == SpanVersion.TRACE_V2 || version == SpanVersion.TRACE_V3) {
    spanChunkBo.setTraceTime(version, keyTime);
}

Type guard

boolean isSupportedChunkVersion(int v) {
    return v == SpanVersion.TRACE_V2 || v == SpanVersion.TRACE_V3;
}

Try / catch

try {
    spanChunkBo.setTraceTime(version, keyTime);
} catch (IllegalArgumentException e) {
    logger.warn("Unsupported span chunk trace version " + version + ", skipping row", e);
}

Prevention

Always branch on SpanVersion constants before calling version-sensitive setters
Gate deserialization paths on the row's version byte read from the same record
Add integration tests covering V2 and V3 (and one unsupported) version fixtures

When it happens

Trigger: Calling setTraceTime(version, keyTime) with a version other than SpanVersion.TRACE_V2 or TRACE_V3, typically when decoding a span chunk serialized with an unsupported/unknown trace version via readSpanChunkValue/bind or when mapping/transforming span chunks with a wrong version.

Common situations: Reading HBase rows written by an older/newer Pinpoint agent whose trace version byte is not V2/V3; corrupted or hand-crafted serialized span data; mixing trace format versions during migration between TRACE_V2 and TRACE_V3 storage schemas.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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