apache/hadoop · error · IllegalStateException

Unsupported protocol found when creating the proxy connectio

Error message

Unsupported protocol found when creating the proxy connection to NameNode: {}

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/NameNodeProxies.java:211

          ugi, alignmentContext);
    } else if (xface == RefreshAuthorizationPolicyProtocol.class) {
      proxy = (T) createNNProxyWithRefreshAuthorizationPolicyProtocol(nnAddr,
          conf, ugi, alignmentContext);
    } else if (xface == RefreshCallQueueProtocol.class) {
      proxy = (T) createNNProxyWithRefreshCallQueueProtocol(nnAddr, conf, ugi,
          alignmentContext);
    } else if (xface == InMemoryAliasMapProtocol.class) {
      proxy = (T) createNNProxyWithInMemoryAliasMapProtocol(nnAddr, conf, ugi,
          alignmentContext);
    } else if (xface == BalancerProtocols.class) {
      proxy = (T) createNNProxyWithBalancerProtocol(nnAddr, conf, ugi,
          withRetries, fallbackToSimpleAuth, alignmentContext);
    } else {
      String message = "Unsupported protocol found when creating the proxy " +
          "connection to NameNode: " +
          ((xface != null) ? xface.getClass().getName() : "null");
      LOG.error(message);
      throw new IllegalStateException(message);
    }

    return new ProxyAndInfo<T>(proxy, dtService, nnAddr);
  }

  private static InMemoryAliasMapProtocol createNNProxyWithInMemoryAliasMapProtocol(
      InetSocketAddress address, Configuration conf, UserGroupInformation ugi,
      AlignmentContext alignmentContext) throws IOException {
    AliasMapProtocolPB proxy = createNameNodeProxy(
        address, conf, ugi, AliasMapProtocolPB.class, 30000, alignmentContext);
    return new InMemoryAliasMapProtocolClientSideTranslatorPB(proxy);
  }

  private static JournalProtocol createNNProxyWithJournalProtocol(
      InetSocketAddress address, Configuration conf, UserGroupInformation ugi,
      AlignmentContext alignmentContext) throws IOException {
    JournalProtocolPB proxy = createNameNodeProxy(address,
        conf, ugi, JournalProtocolPB.class, 30000, alignmentContext);

View on GitHub (pinned to 2add963021)

Solutions

1. Use one of the supported protocol interfaces - ClientProtocol for standard client RPC
2. For custom protocols, build the RPC proxy directly with RPC.getProtocolProxy/Builder instead of NameNodeProxies
3. Verify the exact Hadoop version's createProxy if-chain and align your classpath

Example fix

// before
NameNodeProxies.createProxy(conf, nnAddr, MyCustomProto.class, ugi, false, fallback);
// after: use the supported client interface
NameNodeProxies.createProxy(conf, nnAddr, ClientProtocol.class, ugi, false, fallback);

import java.util.Set;

private static final Set<Class<?>> NN_PROXY_PROTOCOLS = Set.of(
    org.apache.hadoop.hdfs.protocol.ClientProtocol.class,
    org.apache.hadoop.hdfs.server.protocol.NamenodeProtocol.class,
    org.apache.hadoop.hdfs.protocol.AliasMapProtocolProtocolMarker.class /* marker */);

static void assertSupportedProtocol(Class<?> xface) {
  if (xface == null || !NN_PROXY_PROTOCOLS.contains(xface)) {
    throw new IllegalArgumentException(
        "Unsupported NN proxy protocol: " + (xface == null ? "null" : xface.getName())
        + " - use ClientProtocol/NamenodeProtocol or build RPC directly");
  }
}

static boolean isSupportedNnProxyProtocol(Class<?> xface) {
  return xface != null &&
      (xface.equals(org.apache.hadoop.hdfs.protocol.ClientProtocol.class)
       || xface.equals(org.apache.hadoop.hdfs.server.protocol.NamenodeProtocol.class));
}

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown protocol to name node: {protocol}
• Datanode {datanode} not found.
• Failed to report bad block {} to namenode.
• Namenode is in startup mode
• Illagal value: {NAME} = {value} < MIN = {MIN}

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