{"record":{"id":"d65feafe629948b8","repo":"apache/hadoop","slug":"unknown-protocol-protocolname","errorCode":null,"errorMessage":"\"Unknown protocol: \" + protocolName","messagePattern":"\"Unknown protocol: \" \\+ protocolName","errorType":"exception","errorClass":"AuthorizationException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java","lineNumber":3915,"sourceCode":"  /**\n   * Authorize the incoming client connection.\n   * \n   * @param user client user\n   * @param protocolName - the protocol\n   * @param addr InetAddress of incoming connection\n   * @throws AuthorizationException when the client isn't authorized to talk the protocol\n   */\n  private void authorize(UserGroupInformation user, String protocolName,\n      InetAddress addr) throws AuthorizationException {\n    if (authorize) {\n      if (protocolName == null) {\n        throw new AuthorizationException(\"Null protocol not authorized\");\n      }\n      Class<?> protocol = null;\n      try {\n        protocol = getProtocolClass(protocolName, getConf());\n      } catch (ClassNotFoundException cfne) {\n        throw new AuthorizationException(\"Unknown protocol: \" + \n                                         protocolName);\n      }\n      serviceAuthorizationManager.authorize(user, protocol, getConf(), addr);\n    }\n  }\n  \n  /**\n   * Get the port on which the IPC Server is listening for incoming connections.\n   * This could be an ephemeral port too, in which case we return the real\n   * port on which the Server has bound.\n   * @return port on which IPC Server is listening\n   */\n  public int getPort() {\n    return port;\n  }\n  \n  /**\n   * The number of open RPC conections","sourceCodeStart":3897,"sourceCodeEnd":3933,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java#L3897-L3933","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Confirm the exact protocol class exists on the server: check `hadoop classpath` and inspect jars (jar -tf ... | grep <ProtocolName>).","Align the client's hadoop-common/hadoop-hdfs jars to the server version so both sides agree on the protocol class name.","If it is a custom protocol, ship its jar to all server nodes and restart the daemon.","Inspect the build for shade/relocate plugins that rewrite package names of IPC protocol classes."],"exampleFix":"# before: client on hadoop 2.x talking to 3.x server\nexport HADOOP_CLASSPATH=old-hadoop-common-2.8.jar\n\n# after: match server version\nexport HADOOP_CLASSPATH=hadoop-common-3.3.6.jar","handlingStrategy":"try-catch","validationCode":"// Client-side sanity: the protocol class must at least resolve locally (catches typos;\n// server-side classpath must still be verified separately)\nClass<?> p = Class.forName(protocolName);\nif (!MyProtocol.class.isAssignableFrom(p)) throw new IllegalArgumentException(\"bad protocol\");","typeGuard":null,"tryCatchPattern":"try {\n  proxy.call();\n} catch (RemoteException re) {\n  if (re.getMessage() != null && re.getMessage().startsWith(\"Unknown protocol\")) {\n    // protocol class missing on the server classpath / version mismatch\n    throw new ClientServerVersionMismatchException(re.getMessage(), re);\n  }\n  throw re;\n}","preventionTips":["Deploy custom protocol jars to every server node before enabling the clients that use them.","Pin client hadoop jar versions to the server version in your build (hadoop-client provided-scope dependency).","Audit shade/relocate plugins so org.apache.hadoop.ipc protocol class names are not rewritten on one side only."],"tags":["hadoop","ipc","authorization","class-not-found","classpath","version-mismatch"],"backgroundTag":"class-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}