{"record":{"id":"9365c91cad6ebc35","repo":"apache/hadoop","slug":"unknown-protocol-to-name-node-protocol","errorCode":null,"errorMessage":"Unknown protocol to name node: {protocol}","messagePattern":"Unknown protocol to name node: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNode.java","lineNumber":436,"sourceCode":"  \n  public long getProtocolVersion(String protocol, \n                                 long clientVersion) throws IOException {\n    if (protocol.equals(ClientProtocol.class.getName())) {\n      return ClientProtocol.versionID; \n    } else if (protocol.equals(DatanodeProtocol.class.getName())){\n      return DatanodeProtocol.versionID;\n    } else if (protocol.equals(NamenodeProtocol.class.getName())){\n      return NamenodeProtocol.versionID;\n    } else if (protocol.equals(RefreshAuthorizationPolicyProtocol.class.getName())){\n      return RefreshAuthorizationPolicyProtocol.versionID;\n    } else if (protocol.equals(RefreshUserMappingsProtocol.class.getName())){\n      return RefreshUserMappingsProtocol.versionID;\n    } else if (protocol.equals(RefreshCallQueueProtocol.class.getName())) {\n      return RefreshCallQueueProtocol.versionID;\n    } else if (protocol.equals(GetUserMappingsProtocol.class.getName())){\n      return GetUserMappingsProtocol.versionID;\n    } else {\n      throw new IOException(\"Unknown protocol to name node: \" + protocol);\n    }\n  }\n    \n  /**\n   * @deprecated Use {@link HdfsClientConfigKeys#DFS_NAMENODE_RPC_PORT_DEFAULT}\n   *             instead.\n   */\n  @Deprecated\n  public static final int DEFAULT_PORT = DFS_NAMENODE_RPC_PORT_DEFAULT;\n  public static final Logger LOG =\n      LoggerFactory.getLogger(NameNode.class.getName());\n  public static final Logger stateChangeLog =\n      LoggerFactory.getLogger(\"org.apache.hadoop.hdfs.StateChange\");\n  public static final Logger blockStateChangeLog =\n      LoggerFactory.getLogger(\"BlockStateChange\");\n  public static final HAState ACTIVE_STATE = new ActiveState();\n  public static final HAState STANDBY_STATE = new StandbyState();\n  public static final HAState OBSERVER_STATE = new StandbyState(true);","sourceCodeStart":418,"sourceCodeEnd":454,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNode.java#L418-L454","documentation":"NameNode.getProtocolVersion answers versionID only for a fixed set of protocols (client protocol handled earlier, DatanodeProtocol, NamenodeProtocol, RefreshAuthorizationPolicyProtocol, RefreshUserMappingsProtocol, RefreshCallQueueProtocol, GetUserMappingsProtocol). Any other protocol class name in the RPC handshake gets IOException 'Unknown protocol to name node'. It is the NameNode refusing an RPC connection that is speaking a protocol it does not host.","triggerScenarios":"An RPC client connects to the NameNode RPC port and negotiates a protocol outside the list: a client jar from a mismatched Hadoop generation whose protocol class names moved, a daemon/utility pointed at the wrong port (e.g., NN port instead of a different service), or a custom client sending an arbitrary protocol name.","commonSituations":"Client hadoop-hdfs-client version differs from the cluster; connecting to dfs.namenode.servicerpc-address with a client protocol or vice versa; mixing vendor distributions (Apache vs vendor forks); leftover legacy code using retired protocol classes.","solutions":["Verify the client targets the real NameNode RPC address: fs.defaultFS / dfs.namenode.rpc-address, not the service RPC or another daemon's port.","Align the client's hadoop-common/hadoop-hdfs-client jar version with the cluster version so protocol class names match.","For custom RPC code, use one of the published protocols or the protobuf-based ClientNamenodeProtocolTranslatorPB / GenericRefreshProtocol instead of retired interfaces.","If mixing distributions, stop: use the cluster's own client jars on the node issuing the calls."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// before connecting, confirm the target really is a NameNode RPC endpoint\nInetSocketAddress isa = new InetSocketAddress(host, port);\ntry (Socket s = new Socket()) { s.connect(isa, 2000); }\nURI dfsUri = URI.create(String.format(\"hdfs://%s:%d\", isa.getHostName(), isa.getPort()));\n// and ensure the client classpath ships the SAME hadoop version as the cluster","typeGuard":"boolean isUnknownProtocolError(IOException e) {\n  return e.getMessage() != null && e.getMessage().startsWith(\"Unknown protocol\");\n}","tryCatchPattern":"catch (IOException e) {\n  if (isUnknownProtocolError(e)) {\n    // do NOT retry: fix the endpoint (fs.defaultFS / dfs.namenode.rpc-address) or align client jars\n    LOG.error(\"protocol mismatch against {}:{} - check client/server versions\", host, port);\n  }\n  throw e;\n}","preventionTips":["Pin client hadoop-hdfs-client/hadoop-common versions to the cluster version in your build.","Always address the cluster through fs.defaultFS rather than hard-coded host:port guesses.","Never mix vendor distributions between client and server; keep a single distribution per cluster."],"tags":["hdfs","rpc","namenode","protocol","client-compatibility"],"backgroundTag":"rpc-protocol-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}