apache/hadoop · error · AuthorizationException

"Unknown protocol: " + protocolName

Error message

"Unknown protocol: " + protocolName

What it means

With service authorization on, the server must load Class.forName(protocolName) for the protocol named in the client's connection header before applying ACLs. If the class cannot be loaded server-side, the ClassNotFoundException is converted into AuthorizationException("Unknown protocol: ..."). Despite the authorization framing, the root cause is class resolution: the server does not have the protocol class the client named.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java:3915

  /**
   * Authorize the incoming client connection.
   * 
   * @param user client user
   * @param protocolName - the protocol
   * @param addr InetAddress of incoming connection
   * @throws AuthorizationException when the client isn't authorized to talk the protocol
   */
  private void authorize(UserGroupInformation user, String protocolName,
      InetAddress addr) throws AuthorizationException {
    if (authorize) {
      if (protocolName == null) {
        throw new AuthorizationException("Null protocol not authorized");
      }
      Class<?> protocol = null;
      try {
        protocol = getProtocolClass(protocolName, getConf());
      } catch (ClassNotFoundException cfne) {
        throw new AuthorizationException("Unknown protocol: " + 
                                         protocolName);
      }
      serviceAuthorizationManager.authorize(user, protocol, getConf(), addr);
    }
  }
  
  /**
   * Get the port on which the IPC Server is listening for incoming connections.
   * This could be an ephemeral port too, in which case we return the real
   * port on which the Server has bound.
   * @return port on which IPC Server is listening
   */
  public int getPort() {
    return port;
  }
  
  /**
   * The number of open RPC conections

View on GitHub (pinned to 2add963021)

Solutions

1. Confirm the exact protocol class exists on the server: check `hadoop classpath` and inspect jars (jar -tf ... | grep <ProtocolName>).
2. Align the client's hadoop-common/hadoop-hdfs jars to the server version so both sides agree on the protocol class name.
3. If it is a custom protocol, ship its jar to all server nodes and restart the daemon.
4. Inspect the build for shade/relocate plugins that rewrite package names of IPC protocol classes.

Example fix

# before: client on hadoop 2.x talking to 3.x server
export HADOOP_CLASSPATH=old-hadoop-common-2.8.jar

# after: match server version
export HADOOP_CLASSPATH=hadoop-common-3.3.6.jar

// Client-side sanity: the protocol class must at least resolve locally (catches typos;
// server-side classpath must still be verified separately)
Class<?> p = Class.forName(protocolName);
if (!MyProtocol.class.isAssignableFrom(p)) throw new IllegalArgumentException("bad protocol");

try {
  proxy.call();
} catch (RemoteException re) {
  if (re.getMessage() != null && re.getMessage().startsWith("Unknown protocol")) {
    // protocol class missing on the server classpath / version mismatch
    throw new ClientServerVersionMismatchException(re.getMessage(), re);
  }
  throw re;
}

When it happens

Trigger: Client and server run mismatched Hadoop versions so the protocol class was moved/renamed; the protocol class lives in a jar missing from the server's classpath; a custom or hand-crafted connection header supplies a wrong/garbled class name.

Common situations: Rolling upgrades with mixed client/server versions; custom RPC protocols whose jar was not deployed to every NameNode/ResourceManager node; shading/relocation builds that move org.apache.hadoop.* classes; typo in a programmatically built protocol name.

Related errors

• Could not find configured fencing method {}
• Unbound ${method}
• RPC response length mismatch
• Unknown method {} called on {} protocol.
• Unknown protocol: {}

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