{"record":{"id":"9d94b0bd48e765ee","repo":"pinpoint-apm/pinpoint","slug":"absolute-start-end-time-is-only-supported-for-trac","errorCode":null,"errorMessage":"absolute start/end time is only supported for TRACE_V3 spans","messagePattern":"absolute start/end time is only supported for TRACE_V3 spans","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/SpanBo.java","lineNumber":201,"sourceCode":"     */\n    public void setTraceTime(int version, long startTime, int elapsedMillis) {\n        if (version == SpanVersion.TRACE_V3) {\n            throw new IllegalArgumentException(\"TRACE_V3 span requires absolute start/end time\");\n        }\n\n        setVersion(version);\n        this.startTime = startTime;\n        this.elapsed = elapsedMillis;\n        this.endTime = DEFAULT_END_TIME;\n    }\n\n    /**\n     * Sets absolute span time for TRACE_V3 data.\n     * startTime/endTime are epoch nanos. elapsedMillis is retained as the compatibility duration.\n     */\n    public void setTraceTime(int version, long startTime, long endTime, int elapsedMillis) {\n        if (version != SpanVersion.TRACE_V3) {\n            throw new IllegalArgumentException(\"absolute start/end time is only supported for TRACE_V3 spans\");\n        }\n        if (endTime == DEFAULT_END_TIME) {\n            throw new IllegalArgumentException(\"TRACE_V3 span end time is required\");\n        }\n        if (endTime < startTime) {\n            throw new IllegalArgumentException(\"span end time must be greater than or equal to start time\");\n        }\n\n        setVersion(version);\n        this.startTime = startTime;\n        this.elapsed = elapsedMillis;\n        this.endTime = endTime;\n    }\n\n    public boolean hasEndTime() {\n        return endTime != DEFAULT_END_TIME;\n    }\n","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons-server/src/main/java/com/navercorp/pinpoint/common/server/bo/SpanBo.java#L183-L219","documentation":"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.","triggerScenarios":"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.","commonSituations":"Unified deserialization code that always calls the absolute-time overload regardless of version; converted legacy tests; copy-pasted bind logic.","solutions":["Use the elapsed-only 3-arg setTraceTime for versions other than TRACE_V3","Branch on SpanVersion.TRACE_V3 before calling setTraceTime","Update readSpanValue/bind to select the overload by the row's version field","Fix hard-coded version constants in tests/migration code"],"exampleFix":"// before\nspan.setTraceTime(SpanVersion.TRACE_V2, start, end, elapsed); // throws\n// after\nif (version == SpanVersion.TRACE_V3) {\n    span.setTraceTime(version, start, end, elapsed);\n} else {\n    span.setTraceTime(version, start, elapsed);\n}","handlingStrategy":"validation","validationCode":"if (version != SpanVersion.TRACE_V3) { span.setTraceTime(version, startTime, elapsedMillis); } else { span.setTraceTime(version, startTime, endTime, elapsedMillis); }","typeGuard":"boolean supportsAbsoluteTime(int version) { return version == SpanVersion.TRACE_V3; }","tryCatchPattern":"try { span.setTraceTime(version, start, end, elapsed); } catch (IllegalArgumentException e) { log.warn(\"absolute time unsupported for version {}: {}\", version, e.getMessage()); }","preventionTips":["Call the 4-arg overload only for TRACE_V3","Derive version from the stored row, not hard-coded constants","Centralize span time binding in one version-aware helper"],"tags":["java","span","api-misuse","versioning"],"backgroundTag":"invalid-argument-value","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}