{"record":{"id":"f673abeeafc8ef40","repo":"pinpoint-apm/pinpoint","slug":"span-chunk-keytime-is-only-supported-for-trace-v2","errorCode":null,"errorMessage":"span chunk keyTime is only supported for TRACE_V2 or TRACE_V3","messagePattern":"span chunk keyTime is only supported for TRACE_V2 or TRACE_V3","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/SpanChunkBo.java","lineNumber":159,"sourceCode":"    private TraceTimeAccessor timeAccessor() {\n        return TraceTimeAccessor.ofVersion(this.version);\n    }\n\n    public long getKeyTimeMillis() {\n        return timeAccessor().toMillis(keyTime);\n    }\n\n    public long getKeyTimeNanos() {\n        return timeAccessor().toNanos(keyTime);\n    }\n\n    /**\n     * Sets the span chunk time fields as one versioned unit.\n     * TRACE_V2 uses epoch millis. TRACE_V3 uses epoch nanos.\n     */\n    public void setTraceTime(int version, long keyTime) {\n        if (version != SpanVersion.TRACE_V2 && version != SpanVersion.TRACE_V3) {\n            throw new IllegalArgumentException(\"span chunk keyTime is only supported for TRACE_V2 or TRACE_V3\");\n        }\n        setVersion(version);\n        this.keyTime = keyTime;\n    }\n\n    public String getEndPoint() {\n        return endPoint;\n    }\n\n    public void setEndPoint(String endPoint) {\n        this.endPoint = endPoint;\n    }\n\n    @Override\n    public long getCollectorAcceptTime() {\n        return collectorAcceptTime;\n    }\n","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/SpanChunkBo.java#L141-L177","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nspanChunkBo.setTraceTime(unknownVersion, keyTime);\n// after\nif (version == SpanVersion.TRACE_V2 || version == SpanVersion.TRACE_V3) {\n    spanChunkBo.setTraceTime(version, keyTime);\n} else {\n    logger.warn(\"Unsupported span chunk trace version: \" + version);\n}","handlingStrategy":"validation","validationCode":"if (version == SpanVersion.TRACE_V2 || version == SpanVersion.TRACE_V3) {\n    spanChunkBo.setTraceTime(version, keyTime);\n}","typeGuard":"boolean isSupportedChunkVersion(int v) {\n    return v == SpanVersion.TRACE_V2 || v == SpanVersion.TRACE_V3;\n}","tryCatchPattern":"try {\n    spanChunkBo.setTraceTime(version, keyTime);\n} catch (IllegalArgumentException e) {\n    logger.warn(\"Unsupported span chunk trace version \" + version + \", skipping row\", e);\n}","preventionTips":["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"],"tags":["java","serialization","trace-versioning"],"backgroundTag":"invalid-enum-value","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}