{"record":{"id":"d894aef55fb8a665","repo":"apache/seatunnel","slug":"invalid-stain-trace-payload","errorCode":null,"errorMessage":"Invalid stain trace payload","messagePattern":"Invalid stain trace payload","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"warning","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/trace/StainTracePayload.java","lineNumber":55,"sourceCode":"    private static final int START_TS_OFFSET = TRACE_ID_OFFSET + 8;\n    private static final int COUNT_OFFSET = START_TS_OFFSET + 8;\n\n    /**\n     * Creates a new payload header for a freshly sampled row before any stage entries are appended.\n     */\n    public static byte[] init(long traceId, long startTsMs) {\n        ByteBuffer buffer = ByteBuffer.allocate(HEADER_LENGTH).order(ByteOrder.BIG_ENDIAN);\n        buffer.putInt(MAGIC);\n        buffer.putShort(VERSION);\n        buffer.putLong(traceId);\n        buffer.putLong(startTsMs);\n        buffer.putShort((short) 0);\n        return buffer.array();\n    }\n\n    public static long readTraceId(byte[] payload) {\n        if (!isValid(payload)) {\n            throw new IllegalArgumentException(\"Invalid stain trace payload\");\n        }\n        return ByteBuffer.wrap(payload).order(ByteOrder.BIG_ENDIAN).getLong(TRACE_ID_OFFSET);\n    }\n\n    public static boolean isValid(byte[] payload) {\n        if (payload == null || payload.length < HEADER_LENGTH) {\n            return false;\n        }\n        ByteBuffer buffer = ByteBuffer.wrap(payload).order(ByteOrder.BIG_ENDIAN);\n        int magic = buffer.getInt(0);\n        if (magic != MAGIC) {\n            return false;\n        }\n        short ver = buffer.getShort(4);\n        if (ver != VERSION) {\n            return false;\n        }\n        int count = readUnsignedShort(payload, COUNT_OFFSET);","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/trace/StainTracePayload.java#L37-L73","documentation":"StainTracePayload.readTraceId() extracts the 8-byte big-endian trace id from a stain-trace payload byte array. It first validates the payload via isValid() (null check, minimum header length, and magic/version checks); a payload failing validation throws IllegalArgumentException with this message.","triggerScenarios":"readTraceId(payload) called with a null payload, a payload shorter than HEADER_LENGTH, or a payload whose header bytes (magic/format marker) do not match the expected stain-trace format.","commonSituations":"Corrupted or truncated trace payload in transit or persisted state; cross-version incompatibility where an older node writes a different payload format; custom code hand-crafting the byte array incorrectly (wrong endianness or missing header).","solutions":["Check payload validity yourself before decoding: call StainTracePayload.isValid(payload) first.","Verify the payload was produced by the same SeaTunnel version (format/header compatibility).","Trace where the byte[] originated; re-generate or re-capture the trace payload if corrupted.","If hand-building payloads, use StainTracePayload's write/serialize API instead of manual ByteBuffer code."],"exampleFix":"// before: decode without checking\nlong id = StainTracePayload.readTraceId(bytes);\n// after: validate first\nif (StainTracePayload.isValid(bytes)) {\n    long id = StainTracePayload.readTraceId(bytes);\n} else {\n    log.warn(\"skip invalid stain trace payload, len=\" + (bytes == null ? -1 : bytes.length));\n}","handlingStrategy":"type-guard","validationCode":"if (payload == null || payload.length < StainTracePayload.HEADER_LENGTH || !StainTracePayload.isValid(payload)) { /* skip or regenerate */ }","typeGuard":"boolean hasValidTracePayload(byte[] payload) { return payload != null && payload.length >= StainTracePayload.HEADER_LENGTH && StainTracePayload.isValid(payload); }","tryCatchPattern":"try { long id = StainTracePayload.readTraceId(payload); } catch (IllegalArgumentException e) { if (e.getMessage().equals(\"Invalid stain trace payload\")) { log.warn(\"bad trace payload, dropping\"); } else { throw e; } }","preventionTips":["Always call isValid() before readTraceId()","Keep SeaTunnel versions consistent across nodes writing/reading payloads","Use the official serialize API rather than hand-crafted byte arrays"],"tags":["tracing","serialization","payload-validation","observability"],"backgroundTag":"schema-validation-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}