{"record":{"id":"e5cfc78a88db6f4d","repo":"apache/druid","slug":"failed-to-deserialize-rowsignature","errorCode":null,"errorMessage":"Failed to deserialize RowSignature","messagePattern":"Failed to deserialize RowSignature","errorType":"exception","errorClass":"RE","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/frame/wire/FrameWireTransferable.java","lineNumber":129,"sourceCode":"    final int typeCodeLen = 0xFF & theBytes.get();\n    theBytes.position(theBytes.position() + typeCodeLen);\n\n    // Read flags.\n    final byte flags = theBytes.get();\n    final boolean hasSignature = (flags & HAS_SIGNATURE) != 0;\n\n    final RowSignature signature;\n    if (hasSignature) {\n      // Read signature.\n      final int signatureLen = theBytes.getInt();\n      final byte[] signatureBytes = new byte[signatureLen];\n      theBytes.get(signatureBytes);\n\n      try {\n        signature = mapper.readValue(signatureBytes, RowSignature.class);\n      }\n      catch (IOException e) {\n        throw new RE(e, \"Failed to deserialize RowSignature\");\n      }\n    } else {\n      signature = null;\n    }\n\n    // Read remaining bytes as a Frame.\n    final Frame frame = Frame.wrap(Memory.wrap(theBytes, ByteOrder.LITTLE_ENDIAN)\n                                         .region(theBytes.position(), theBytes.remaining()));\n\n    if (frame.type().isRowBased()) {\n      return new RowBasedFrameRowsAndColumns(frame, signature);\n    } else {\n      return new ColumnBasedFrameRowsAndColumns(frame, signature);\n    }\n  }\n\n  /**\n   * Deserializer for frames.","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/frame/wire/FrameWireTransferable.java#L111-L147","documentation":"FrameWireTransferable.deserializeFrame reads an optional serialized RowSignature from the frame's wire bytes and deserializes it with Jackson. A corrupt, truncated, or incompatible signature blob causes an IOException, rethrown as RE('Failed to deserialize RowSignature'). It indicates the binary frame payload is malformed or from an incompatible writer.","triggerScenarios":"Deserializing a frame whose signature byte section is corrupt/truncated, written by an incompatible Druid version, or whose buffer offsets (signature length/bytes) were miscomputed.","commonSituations":"Network/channel corruption between clusters or across native-query/MSQ data exchange; version skew where the wire format changed; manually sliced or re-serialized frames in custom transport code.","solutions":["Verify the frame bytes are complete and not truncated in transit; check the serialization/deserialization code paths for offset bugs","Align Druid versions between the producing and consuming nodes","Capture the underlying IOException (it is the cause of the RE) to identify exact Jackson failure and fix the payload","Re-generate/re-run the query that produced the frame rather than retrying the bad payload"],"exampleFix":"// before\nFrame frame = FrameWireTransferable.deserializeFrame(bytes, mapper); // bytes truncated\n// after\nByteBuffer buf = bytes.duplicate();\nif (buf.remaining() < expectedHeaderSize) {\n  throw new IllegalStateException(\"Frame truncated: \" + buf.remaining());\n}\nFrame frame = FrameWireTransferable.deserializeFrame(bytes, mapper);","handlingStrategy":"try-catch","validationCode":"if (bytes.remaining() < MIN_FRAME_HEADER) { throw new IllegalStateException(\"frame truncated\"); }","typeGuard":"null","tryCatchPattern":"try { deserializeFrame(bytes, mapper); } catch (RE e) { log.error(\"RowSignature deserialize failed; cause={}\", e.getCause()); /* regenerate or reject frame */ }","preventionTips":["Inspect the IOException cause for exact failure","Keep producing/consuming Druid versions aligned","Checksum frames in custom transports to catch truncation"],"tags":["deserialization","wire-format","frame"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}