apache/hadoop · error · IOException

Port {} specified in URI {} but host '{}' is a logical (HA)

Error message

Port {} specified in URI {} but host '{}' is a logical (HA) namenode and does not use port information.

What it means

For a logical (HA) nameservice URI, the failover provider iterates individual NameNode addresses from configuration, so the authority carries no port; if the URI specifies a positive port that is not the default RPC port (8020), NameNodeProxiesClient rejects it with this IOException before creating proxies. Port 8020 is tolerated as the default; any other port (e.g., 9000, 9820 custom) triggers the error.

Source

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

    } 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;
  }

  /** Gets the configured Failover proxy provider's class */
  @VisibleForTesting
  public static <T> Class<FailoverProxyProvider<T>> getFailoverProxyProviderClass(
      Configuration conf, URI nameNodeUri) throws IOException {
    if (nameNodeUri == null) {
      return null;
    }
    String host = nameNodeUri.getHost();
    String configKey = HdfsClientConfigKeys.Failover.PROXY_PROVIDER_KEY_PREFIX

View on GitHub (pinned to 2add963021)

Solutions

1. Drop the port from the logical URI: hdfs://myNameservice/path
2. Or keep the default port hdfs://myNameservice:8020/path, which is accepted
3. If you truly need a port, address an individual NameNode host directly (non-HA style) instead of the logical nameservice
4. Audit fs.defaultFS, job configs, and URL templates for auto-appended ports

Example fix

// before
Path p = new Path("hdfs://myNameservice:9000/user/me/file"); // logical URI with port

// after
Path p = new Path("hdfs://myNameservice/user/me/file"); // port-less logical URI

URI u = path.toUri();
if (conf.get("dfs.ha.namenodes." + u.getHost()) != null) { // logical HA host
  int port = u.getPort();
  if (port > 0 && port != 8020) {
    path = new Path("hdfs://" + u.getHost() + u.getPath()); // strip the port
  }
}

try {
  fs = FileSystem.get(nameNodeUri, conf);
} catch (IOException e) {
  if (e.getMessage().contains("logical (HA) namenode")) {
    URI stripped = URI.create("hdfs://" + nameNodeUri.getHost() + "/");
    fs = FileSystem.get(stripped, conf);
  } else throw e;
}

When it happens

Trigger: Calling new Path("hdfs://myNameservice:9000/user/a") or setting fs.defaultFS/dfs.nameservices URI with an explicit port while dfs.ha.namenodes.myNameservice failover applies; checkPort is true for standard client proxy creation, so typical DFSClient/FileSystem.get() calls enforce it.

Common situations: Users carrying over standalone-NN URIs (hdfs://host:9000) to HA by only swapping the host for the nameservice; job frameworks that auto-append a port to fs.defaultFS; tools validating URIs constructed from host+port templates.

Related errors

• Couldn't create proxy provider {}
• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with
• FileSystem {} is not a DFS.
• The journal edits cache is not enabled, which is a requireme

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