apache/hadoop · error · IOException

Couldn't create proxy provider {}

Error message

Couldn't create proxy provider {}

What it means

While creating the HA failover proxy, NameNodeProxiesClient instantiates the configured FailoverProxyProvider class inside a try block; any exception from the provider's constructor (most often ConfiguredFailoverProxyProvider failing to resolve per-NameNode addresses) is caught here. If the cause is an IOException it is rethrown directly; otherwise it is wrapped with 'Couldn't create proxy provider <class>'. The root cause is almost always incomplete HA configuration for the nameservice.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/NameNodeProxiesClient.java:256

          .getConstructor(Configuration.class, URI.class,
              Class.class, HAProxyFactory.class);
      FailoverProxyProvider<T> provider = ctor.newInstance(conf, nameNodeUri,
          xface, proxyFactory);

      // If the proxy provider is of an old implementation, wrap it.
      if (!(provider instanceof AbstractNNFailoverProxyProvider)) {
        providerNN = new WrappedFailoverProxyProvider<>(provider);
      } else {
        providerNN = (AbstractNNFailoverProxyProvider<T>)provider;
      }
    } catch (Exception e) {
      final String message = "Couldn't create proxy provider " +
          failoverProxyProviderClass;
      LOG.debug(message, e);
      if (e.getCause() instanceof IOException) {
        throw (IOException) e.getCause();
      } else {
        throw new IOException(message, e);
      }
    }

    // Check the port in the URI, if it is logical.
    if (checkPort && providerNN.useLogicalURI()) {
      int port = nameNodeUri.getPort();
      if (port > 0 &&
          port != HdfsClientConfigKeys.DFS_NAMENODE_RPC_PORT_DEFAULT) {
        // Throwing here without any cleanup is fine since we have not
        // actually created the underlying proxies yet.
        throw new IOException("Port " + port + " specified in URI "
            + nameNodeUri + " but host '" + nameNodeUri.getHost()
            + "' is a logical (HA) namenode"
            + " and does not use port information.");
      }
    }
    providerNN.setFallbackToSimpleAuth(fallbackToSimpleAuth);
    return providerNN;

View on GitHub (pinned to 2add963021)

Solutions

1. Ship the cluster's hdfs-site.xml/core-site.xml to the client and verify dfs.ha.namenodes.<nameservice> plus every dfs.namenode.rpc-address.<nameservice>.<id> is present
2. Check the nested cause in the stack trace — it names the exact missing address/config
3. Confirm fs.defaultFS uses the same logical nameservice string as the dfs.ha.* keys (case/underscore exact)
4. If using a custom failover proxy provider, ensure its jar and constructor dependencies are on the client classpath

Example fix

<!-- before -->
<property><name>fs.defaultFS</name><value>hdfs://myNameservice</value></property>
<!-- no dfs.ha.namenodes.* entries -->

<!-- after -->
<property><name>fs.defaultFS</name><value>hdfs://myNameservice</value></property>
<property><name>dfs.ha.namenodes.myNameservice</name><value>nn1,nn2</value></property>
<property><name>dfs.namenode.rpc-address.myNameservice.nn1</name><value>nn1-host:8020</value></property>
<property><name>dfs.namenode.rpc-address.myNameservice.nn2</name><value>nn2-host:8020</value></property>

// Validate HA config before creating clients:
String ns = uri.getHost();
String namenodes = conf.get("dfs.ha.namenodes." + ns);
if (namenodes == null) throw new IllegalArgumentException("dfs.ha.namenodes." + ns + " missing");
for (String id : namenodes.split(",")) {
  if (conf.get("dfs.namenode.rpc-address." + ns + "." + id) == null)
    throw new IllegalArgumentException("dfs.namenode.rpc-address." + ns + "." + id + " missing");
}

try {
  fs = FileSystem.get(new URI("hdfs://myNameservice"), conf);
} catch (IOException e) {
  // inspect e.getCause(): the nested IOException names the missing HA property
  log.error("HA proxy creation failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
  throw e;
}

When it happens

Trigger: Creating a DFSClient against an HA nameservice (hdfs://myNameservice) where dfs.ha.namenodes.myNameservice is unset/misnamed, dfs.namenode.rpc-address.myNameservice.<nn> entries are missing, or the configured provider class's constructor throws (bad URI, unknown host) for any individual NameNode.

Common situations: Client side lacks the cluster's hdfs-site.xml HA block; typo in the nameservice (dfs.ha.namenodes.mynamservice); HA enabled on the cluster but client config only has fs.defaultFS pointing at the logical URI; custom failover provider classes whose constructor requirements changed between versions.

Related errors

• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with
• Invalid configuration: a shared edits dir must not be specif
• Multiple shared edits directories are not yet supported
• The option dfs.namenode.support.allow.format is set to false

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