apache/hadoop · error · IOException

Serverside implements {}. The following requested protocol i

Error message

Serverside implements {}. The following requested protocol is unknown: {}

What it means

Same protocol negotiation guard as HAServiceProtocolServerSideTranslatorPB, but for the ZKFC control RPC: the server implements org.apache.hadoop.ha.protocolPB.ZKFCProtocolPB and rejects any client requesting a different protocol name with IOException. This RPC is used by 'hdfs haadmin -failover' to talk to each ZKFC's local port (default 8019).

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ha/protocolPB/ZKFCProtocolServerSideTranslatorPB.java:78

    try {
      server.gracefulFailover();
      return GracefulFailoverResponseProto.getDefaultInstance();
    } catch (IOException e) {
      throw new ServiceException(e);
    }
  }

  @Override
  public long getProtocolVersion(String protocol, long clientVersion)
      throws IOException {
    return RPC.getProtocolVersion(ZKFCProtocolPB.class);
  }

  @Override
  public ProtocolSignature getProtocolSignature(String protocol,
      long clientVersion, int clientMethodsHash) throws IOException {
    if (!protocol.equals(RPC.getProtocolName(ZKFCProtocolPB.class))) {
      throw new IOException("Serverside implements " +
          RPC.getProtocolName(ZKFCProtocolPB.class) +
          ". The following requested protocol is unknown: " + protocol);
    }

    return ProtocolSignature.getProtocolSignature(clientMethodsHash,
        RPC.getProtocolVersion(ZKFCProtocolPB.class),
        HAServiceProtocolPB.class);
  }

}

View on GitHub (pinned to 2add963021)

Solutions

1. Match client and server Hadoop versions (hadoop-common jar on the haadmin host must equal the cluster's)
2. Check for duplicate/relocated hadoop-common jars on the client classpath
3. Verify you are connecting to the ZKFC RPC address (dfs.ha.zkfc.port, default 8019) with a ZKFCProtocolPB proxy, not another protocol

// verify the ZKFC RPC endpoint speaks the protocol you built against
String expected = "org.apache.hadoop.ha.protocolPB.ZKFCProtocolPB";
assert expected.equals(HAServiceProtocolPB.class.getName().replace("HAService", "ZKFC")) : "sanity";
// real check: run 'hadoop version' on gateway and cluster and compare

try {
  zkfcProxy.gracefulFailover(timeout);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("requested protocol is unknown")) {
    throw new IllegalStateException("hadoop version mismatch between haadmin client and ZKFC", e);
  }
}

When it happens

Trigger: 'hdfs haadmin -failover' or ZKFCProtocol proxy creation where the client's hadoop-common provides a different protocol class (version skew); a hand-written client sending another protocol name to the ZKFC RPC address.

Common situations: Running hadoop-client of a different minor release than the cluster nodes; deploying a patched hadoop-common only on servers; gateway hosts with stale jars.

Related errors

• Serverside implements {}. The following requested protocol i
• Unknown protocol: {}
• {} is in observer state. Cannot be failover target
• Unexpected ZooKeeper issue fetching active node info
• RPC response length mismatch

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