apache/hadoop · error · IOException

Unknown protocol to name node: {protocol}

Error message

Unknown protocol to name node: {protocol}

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNode.java:436

  
  public long getProtocolVersion(String protocol, 
                                 long clientVersion) throws IOException {
    if (protocol.equals(ClientProtocol.class.getName())) {
      return ClientProtocol.versionID; 
    } else if (protocol.equals(DatanodeProtocol.class.getName())){
      return DatanodeProtocol.versionID;
    } else if (protocol.equals(NamenodeProtocol.class.getName())){
      return NamenodeProtocol.versionID;
    } else if (protocol.equals(RefreshAuthorizationPolicyProtocol.class.getName())){
      return RefreshAuthorizationPolicyProtocol.versionID;
    } else if (protocol.equals(RefreshUserMappingsProtocol.class.getName())){
      return RefreshUserMappingsProtocol.versionID;
    } else if (protocol.equals(RefreshCallQueueProtocol.class.getName())) {
      return RefreshCallQueueProtocol.versionID;
    } else if (protocol.equals(GetUserMappingsProtocol.class.getName())){
      return GetUserMappingsProtocol.versionID;
    } else {
      throw new IOException("Unknown protocol to name node: " + protocol);
    }
  }
    
  /**
   * @deprecated Use {@link HdfsClientConfigKeys#DFS_NAMENODE_RPC_PORT_DEFAULT}
   *             instead.
   */
  @Deprecated
  public static final int DEFAULT_PORT = DFS_NAMENODE_RPC_PORT_DEFAULT;
  public static final Logger LOG =
      LoggerFactory.getLogger(NameNode.class.getName());
  public static final Logger stateChangeLog =
      LoggerFactory.getLogger("org.apache.hadoop.hdfs.StateChange");
  public static final Logger blockStateChangeLog =
      LoggerFactory.getLogger("BlockStateChange");
  public static final HAState ACTIVE_STATE = new ActiveState();
  public static final HAState STANDBY_STATE = new StandbyState();
  public static final HAState OBSERVER_STATE = new StandbyState(true);

View on GitHub (pinned to 2add963021)

Solutions

1. Verify the client targets the real NameNode RPC address: fs.defaultFS / dfs.namenode.rpc-address, not the service RPC or another daemon's port.
2. Align the client's hadoop-common/hadoop-hdfs-client jar version with the cluster version so protocol class names match.
3. For custom RPC code, use one of the published protocols or the protobuf-based ClientNamenodeProtocolTranslatorPB / GenericRefreshProtocol instead of retired interfaces.
4. If mixing distributions, stop: use the cluster's own client jars on the node issuing the calls.

// before connecting, confirm the target really is a NameNode RPC endpoint
InetSocketAddress isa = new InetSocketAddress(host, port);
try (Socket s = new Socket()) { s.connect(isa, 2000); }
URI dfsUri = URI.create(String.format("hdfs://%s:%d", isa.getHostName(), isa.getPort()));
// and ensure the client classpath ships the SAME hadoop version as the cluster

boolean isUnknownProtocolError(IOException e) {
  return e.getMessage() != null && e.getMessage().startsWith("Unknown protocol");
}

catch (IOException e) {
  if (isUnknownProtocolError(e)) {
    // do NOT retry: fix the endpoint (fs.defaultFS / dfs.namenode.rpc-address) or align client jars
    LOG.error("protocol mismatch against {}:{} - check client/server versions", host, port);
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unsupported protocol found when creating the proxy connectio
• Datanode {datanode} not found.
• Failed to report bad block {} to namenode.
• Namenode is in startup mode
• Serverside implements {}. The following requested protocol i

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/9365c91cad6ebc35. Report an issue: GitHub.