apache/hadoop · error · RpcNoSuchProtocolException

Unknown protocol: {}

Error message

Unknown protocol: {}

What it means

Server-side in ProtobufRpcEngine2.ProtoBufRpcInvoker.getProtocolImpl: the (protocolName, clientVersion) pair must exist in the server's registered protocol map; if no implementation of that protocol name exists at all, RpcNoSuchProtocolException('Unknown protocol: X') is thrown back to the client. If the name exists but the version differs you get RPC.VersionMismatch instead — this specific message means the protocol is simply not registered on that server.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/ProtobufRpcEngine2.java:529

        return RPC_INVOKER;
      }
      return super.getServerRpcInvoker(rpcKind);
    }

    /**
     * Protobuf invoker for {@link RpcInvoker}.
     */
    static class ProtoBufRpcInvoker implements RpcInvoker {
      private static ProtoClassProtoImpl getProtocolImpl(RPC.Server server,
          String protoName, long clientVersion) throws RpcServerException {
        ProtoNameVer pv = new ProtoNameVer(protoName, clientVersion);
        ProtoClassProtoImpl impl =
            server.getProtocolImplMap(RPC.RpcKind.RPC_PROTOCOL_BUFFER).get(pv);
        if (impl == null) { // no match for Protocol AND Version
          VerProtocolImpl highest = server.getHighestSupportedProtocol(
              RPC.RpcKind.RPC_PROTOCOL_BUFFER, protoName);
          if (highest == null) {
            throw new RpcNoSuchProtocolException(
                "Unknown protocol: " + protoName);
          }
          // protocol supported but not the version that client wants
          throw new RPC.VersionMismatch(protoName, clientVersion,
              highest.version);
        }
        return impl;
      }

      @Override
      /**
       * This is a server side method, which is invoked over RPC. On success
       * the return response has protobuf response payload. On failure, the
       * exception name and the stack trace are returned in the response.
       * See {@link HadoopRpcResponseProto}
       *
       * In this method there three types of exceptions possible and they are
       * returned in response as follows.

View on GitHub (pinned to 2add963021)

Solutions

1. Verify the target address is the daemon that serves the protocol (NameNode RPC address for ClientNamenodeProtocol, etc.).
2. On custom servers, register the protocol: server.addProtocol(RpcKind.RPC_PROTOCOL_BUFFER, MyProtocolPB.class, impl).
3. Ensure the exact same protocol class (name) is used on both sides; avoid jar shading that rewrites class names asymmetrically.

Example fix

// before (custom server)
RPC.Server server = new RPC.Builder(conf)
    .setProtocol(MyProtocolPB.class).setInstance(impl)
    .setBindAddress("0.0.0.0").setPort(8020).build();
// client sends OtherProtocolPB -> Unknown protocol: OtherProtocolPB

// after
server.addProtocol(RPC.RpcKind.RPC_PROTOCOL_BUFFER,
    OtherProtocolPB.class, otherImpl); // register every served protocol

// client capability check before first real call
try {
  proxy.getProtocolMetaInfoNameVersion( // cheap handshake on VersionedProtocol paths
      null, GetProtocolSignatureRequestProto.newBuilder().setProtocol(protocolName).build());
} catch (RemoteException e) {
  if (RpcNoSuchProtocolException.class.getName().equals(e.getErrorCode())) {
    throw new IllegalStateException("Server " + addr + " does not serve " + protocolName, e);
  }
  throw e;
}

try {
  return proxy.call(req);
} catch (RemoteException e) {
  if (RpcNoSuchProtocolException.class.getName().equals(e.getErrorCode())) {
    // wrong server or protocol not registered
    throw new IllegalStateException("Wrong endpoint or unregistered protocol", e);
  }
  throw e;
}

When it happens

Trigger: Connecting a client of protocol X to a server that never registered X (wrong server type, e.g., ClientNamenodeProtocol sent to a DataNode); protocol class name mismatch (protoName is compared as text); server built without the protocol handler (custom server forgot addProtocol).

Common situations: Wrong address/port in client config pointing at a different daemon; custom RPC servers missing RPC.getServer(...).addProtocol(...); shade/relocation renaming protocol classes differently on client vs server; older server that predates the protocol.

Related errors

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

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