{"record":{"id":"8820e4cd47a4879f","repo":"apache/hadoop","slug":"version-mismatch-expected-received","errorCode":null,"errorMessage":"Version Mismatch (Expected: {}, Received: {} )","messagePattern":"Version Mismatch \\(Expected: (.+?), Received: (.+?) \\)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/protocol/datatransfer/Receiver.java","lineNumber":74,"sourceCode":"@InterfaceStability.Evolving\npublic abstract class Receiver implements DataTransferProtocol {\n  private final Tracer tracer;\n  protected DataInputStream in;\n\n  protected Receiver(Tracer tracer) {\n    this.tracer = tracer;\n  }\n\n  /** Initialize a receiver for DataTransferProtocol with a socket. */\n  protected void initialize(final DataInputStream in) {\n    this.in = in;\n  }\n\n  /** Read an Op.  It also checks protocol version. */\n  protected final Op readOp() throws IOException {\n    final short version = in.readShort();\n    if (version != DataTransferProtocol.DATA_TRANSFER_VERSION) {\n      throw new IOException( \"Version Mismatch (Expected: \" +\n          DataTransferProtocol.DATA_TRANSFER_VERSION  +\n          \", Received: \" +  version + \" )\");\n    }\n    return Op.read(in);\n  }\n\n  private TraceScope continueTraceSpan(ByteString spanContextBytes,\n                                       String description) {\n    TraceScope scope = null;\n    SpanContext spanContext =\n        TraceUtils.byteStringToSpanContext(spanContextBytes);\n    if (spanContext != null) {\n      scope = tracer.newScope(description, spanContext);\n    }\n    return scope;\n  }\n\n  private TraceScope continueTraceSpan(ClientOperationHeaderProto header,","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/protocol/datatransfer/Receiver.java#L56-L92","documentation":"Every data-transfer connection (DFSClient to DataNode, DN to DN on the xfer port) starts each operation with a short protocol version, DATA_TRANSFER_VERSION. Receiver.readOp rejects any value that differs, throwing IOException with expected vs received before the op is even parsed.","triggerScenarios":"A client or peer DataNode running a Hadoop build whose DATA_TRANSFER_VERSION differs from the serving DataNode; or a non-HDFS program connecting to dfs.datanode.data.port (default 9866) so its bytes decode as a bogus version.","commonSituations":"Version skew during rolling upgrades that skipped incompatible versions; downgraded clients; stray services or port scanners hitting the dataxceiver port; custom native clients hardcoding the wrong version.","solutions":["Align the HDFS client and DataNode versions (rolling upgrades must step only through mutually compatible versions)","Check DataNode logs for the peer address - if it is not an expected client/DN, find and stop whatever is connecting to the xfer port","For custom clients, send the DATA_TRANSFER_VERSION constant of the cluster being targeted"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Client-side preflight: refuse to run against a cluster whose version may differ\nString dnVersion = someDn.getHdfsBlockReportsVersionHint(); // e.g. via DataNode JMX VersionInfo\n// practical form: assert the client's Hadoop version equals the cluster's reported\n// version (jmx `Hadoop:service=DataNode,name=DataNodeInfo` -> Version) before heavy IO","typeGuard":null,"tryCatchPattern":"try {\n  fs.open(path).read();\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Version Mismatch\")) {\n    // data-transfer protocol skew: stop and align client/DN versions; do not retry\n  } else {\n    throw e;\n  }\n}","preventionTips":["Pin client and cluster Hadoop versions; follow the documented upgrade order for rolling upgrades","Watch DN logs for the peer address on version-mismatch errors to find the offending client","Keep nothing else bound to or dialing dfs.datanode.data.port"],"tags":["hdfs","datatransfer","version-mismatch","datanode","protocol","block-io"],"backgroundTag":"protocol-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}