apache/hadoop · error · IOException

Serverside implements {}. The following requested protocol i

Error message

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

What it means

The server-side PB translator for HAServiceProtocol validates that the protocol name sent by the RPC client exactly matches org.apache.hadoop.ha.protocolPB.HAServiceProtocolPB. If the client asks for a different protocol FQCN, the server throws IOException stating what it implements versus what was requested. This is Hadoop's standard protocol negotiation guard and almost always means client/server jar mismatch or the wrong proxy type.

Source

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

        .setState(retState)
        .setReadyToBecomeActive(s.isReadyToBecomeActive());
    if (!s.isReadyToBecomeActive()) {
      ret.setNotReadyReason(s.getNotReadyReason());
    }
    return ret.build();
  }

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

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

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

View on GitHub (pinned to 2add963021)

Solutions

1. Align versions: make the client use the same hadoop-common/hadoop-hdfs artifacts as the server (check 'hadoop version' on both ends)
2. Inspect the client classpath for multiple hadoop-common*.jar versions and keep only one
3. Confirm you are creating the right proxy (HAServiceProtocol via HAServiceProtocolPB) for this endpoint

// client-side sanity before RPC: ensure the protocol class resolves to the expected name
String expected = "org.apache.hadoop.ha.protocolPB.HAServiceProtocolPB";
if (!expected.equals(RPC.getProtocolName(HAServiceProtocolPB.class))) {
  throw new IllegalStateException("unexpected hadoop-common on classpath");
}
// and check versions on both ends: hadoop version

try {
  proxy = HAServiceHelper... // build RPC proxy
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("requested protocol is unknown")) {
    // client/server hadoop version skew - fail fast with a clear config error
  }
}

When it happens

Trigger: An RPC client proxying to the HAServiceProtocol RPC server (NameNode service RPC address) but built against a different Hadoop version where the protobuf protocol class name differs; mixing hadoop-common jars of different versions on one classpath; sending ZKFCProtocol requests to an HAServiceProtocol endpoint.

Common situations: Client applications or custom tooling compiled against one Hadoop release talking to a cluster of another release; fat jars bundling an old hadoop-common; shaded plugins that relocated org.apache.hadoop classes.

Related errors

• Serverside implements {}. The following requested protocol i
• Unknown protocol: {}
• RPC response length mismatch
• Unknown method {} called on {} protocol.
• Unknown method ${methodName} called on ${connectionProtocolN

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