{"record":{"id":"7d00da18080dcba3","repo":"apache/hadoop","slug":"unsupported-protocol-found-when-creating-the-proxy","errorCode":null,"errorMessage":"Unsupported protocol found when creating the proxy connection to NameNode: {}","messagePattern":"Unsupported protocol found when creating the proxy connection to NameNode: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/NameNodeProxies.java","lineNumber":211,"sourceCode":"          ugi, alignmentContext);\n    } else if (xface == RefreshAuthorizationPolicyProtocol.class) {\n      proxy = (T) createNNProxyWithRefreshAuthorizationPolicyProtocol(nnAddr,\n          conf, ugi, alignmentContext);\n    } else if (xface == RefreshCallQueueProtocol.class) {\n      proxy = (T) createNNProxyWithRefreshCallQueueProtocol(nnAddr, conf, ugi,\n          alignmentContext);\n    } else if (xface == InMemoryAliasMapProtocol.class) {\n      proxy = (T) createNNProxyWithInMemoryAliasMapProtocol(nnAddr, conf, ugi,\n          alignmentContext);\n    } else if (xface == BalancerProtocols.class) {\n      proxy = (T) createNNProxyWithBalancerProtocol(nnAddr, conf, ugi,\n          withRetries, fallbackToSimpleAuth, alignmentContext);\n    } else {\n      String message = \"Unsupported protocol found when creating the proxy \" +\n          \"connection to NameNode: \" +\n          ((xface != null) ? xface.getClass().getName() : \"null\");\n      LOG.error(message);\n      throw new IllegalStateException(message);\n    }\n\n    return new ProxyAndInfo<T>(proxy, dtService, nnAddr);\n  }\n\n  private static InMemoryAliasMapProtocol createNNProxyWithInMemoryAliasMapProtocol(\n      InetSocketAddress address, Configuration conf, UserGroupInformation ugi,\n      AlignmentContext alignmentContext) throws IOException {\n    AliasMapProtocolPB proxy = createNameNodeProxy(\n        address, conf, ugi, AliasMapProtocolPB.class, 30000, alignmentContext);\n    return new InMemoryAliasMapProtocolClientSideTranslatorPB(proxy);\n  }\n\n  private static JournalProtocol createNNProxyWithJournalProtocol(\n      InetSocketAddress address, Configuration conf, UserGroupInformation ugi,\n      AlignmentContext alignmentContext) throws IOException {\n    JournalProtocolPB proxy = createNameNodeProxy(address,\n        conf, ugi, JournalProtocolPB.class, 30000, alignmentContext);","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/NameNodeProxies.java#L193-L229","documentation":"NameNodeProxies.createProxy dispatches on a fixed protocol set (ClientProtocol, NamenodeProtocol, InMemoryAliasMapProtocol, BalancerProtocols and the refresh/reconfig-style interfaces in the if-chain). Any other Class passed as xface falls through to an IllegalStateException. Note the message prints xface.getClass().getName(), which for a Class object is 'java.lang.Class', not the interface name.","triggerScenarios":"Calling NameNodeProxies.createProxy (or DFSUtil helpers over it) with a custom protocol interface, a client-side translator class, or a protocol class that moved/renamed across Hadoop versions.","commonSituations":"Custom tooling building NN proxies with non-standard interfaces; version drift in the classpath (e.g. BalancerProtocols lookup changes between releases) so the intended branch no longer matches; passing null xface.","solutions":["Use one of the supported protocol interfaces - ClientProtocol for standard client RPC","For custom protocols, build the RPC proxy directly with RPC.getProtocolProxy/Builder instead of NameNodeProxies","Verify the exact Hadoop version's createProxy if-chain and align your classpath"],"exampleFix":"// before\nNameNodeProxies.createProxy(conf, nnAddr, MyCustomProto.class, ugi, false, fallback);\n// after: use the supported client interface\nNameNodeProxies.createProxy(conf, nnAddr, ClientProtocol.class, ugi, false, fallback);","handlingStrategy":"validation","validationCode":"import java.util.Set;\n\nprivate static final Set<Class<?>> NN_PROXY_PROTOCOLS = Set.of(\n    org.apache.hadoop.hdfs.protocol.ClientProtocol.class,\n    org.apache.hadoop.hdfs.server.protocol.NamenodeProtocol.class,\n    org.apache.hadoop.hdfs.protocol.AliasMapProtocolProtocolMarker.class /* marker */);\n\nstatic void assertSupportedProtocol(Class<?> xface) {\n  if (xface == null || !NN_PROXY_PROTOCOLS.contains(xface)) {\n    throw new IllegalArgumentException(\n        \"Unsupported NN proxy protocol: \" + (xface == null ? \"null\" : xface.getName())\n        + \" - use ClientProtocol/NamenodeProtocol or build RPC directly\");\n  }\n}","typeGuard":"static boolean isSupportedNnProxyProtocol(Class<?> xface) {\n  return xface != null &&\n      (xface.equals(org.apache.hadoop.hdfs.protocol.ClientProtocol.class)\n       || xface.equals(org.apache.hadoop.hdfs.server.protocol.NamenodeProtocol.class));\n}","tryCatchPattern":"catch (IllegalStateException e) around NameNodeProxies.createProxy; note the message prints 'java.lang.Class' for any non-null xface, so log the xface you passed yourself to identify the offending protocol.","preventionTips":["Treat NameNodeProxies as supporting only the well-known protocols; build custom RPC with RPC.Builder","Pin Hadoop versions in build files so protocol classes cannot drift at runtime"],"tags":["hdfs","rpc","proxy","protocol","namenode","internal-api"],"backgroundTag":"rpc-protocol-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}