{"record":{"id":"ccccc6818263c137","repo":"apache/hadoop","slug":"port-specified-in-uri-but-host-is-a-log","errorCode":null,"errorMessage":"Port {} specified in URI {} but host '{}' is a logical (HA) namenode and does not use port information.","messagePattern":"Port (.+?) specified in URI (.+?) but host '(.+?)' is a logical \\(HA\\) namenode and does not use port information\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/NameNodeProxiesClient.java","lineNumber":267,"sourceCode":"    } catch (Exception e) {\n      final String message = \"Couldn't create proxy provider \" +\n          failoverProxyProviderClass;\n      LOG.debug(message, e);\n      if (e.getCause() instanceof IOException) {\n        throw (IOException) e.getCause();\n      } else {\n        throw new IOException(message, e);\n      }\n    }\n\n    // Check the port in the URI, if it is logical.\n    if (checkPort && providerNN.useLogicalURI()) {\n      int port = nameNodeUri.getPort();\n      if (port > 0 &&\n          port != HdfsClientConfigKeys.DFS_NAMENODE_RPC_PORT_DEFAULT) {\n        // Throwing here without any cleanup is fine since we have not\n        // actually created the underlying proxies yet.\n        throw new IOException(\"Port \" + port + \" specified in URI \"\n            + nameNodeUri + \" but host '\" + nameNodeUri.getHost()\n            + \"' is a logical (HA) namenode\"\n            + \" and does not use port information.\");\n      }\n    }\n    providerNN.setFallbackToSimpleAuth(fallbackToSimpleAuth);\n    return providerNN;\n  }\n\n  /** Gets the configured Failover proxy provider's class */\n  @VisibleForTesting\n  public static <T> Class<FailoverProxyProvider<T>> getFailoverProxyProviderClass(\n      Configuration conf, URI nameNodeUri) throws IOException {\n    if (nameNodeUri == null) {\n      return null;\n    }\n    String host = nameNodeUri.getHost();\n    String configKey = HdfsClientConfigKeys.Failover.PROXY_PROVIDER_KEY_PREFIX","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/NameNodeProxiesClient.java#L249-L285","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Drop the port from the logical URI: hdfs://myNameservice/path","Or keep the default port hdfs://myNameservice:8020/path, which is accepted","If you truly need a port, address an individual NameNode host directly (non-HA style) instead of the logical nameservice","Audit fs.defaultFS, job configs, and URL templates for auto-appended ports"],"exampleFix":"// before\nPath p = new Path(\"hdfs://myNameservice:9000/user/me/file\"); // logical URI with port\n\n// after\nPath p = new Path(\"hdfs://myNameservice/user/me/file\"); // port-less logical URI","handlingStrategy":"validation","validationCode":"URI u = path.toUri();\nif (conf.get(\"dfs.ha.namenodes.\" + u.getHost()) != null) { // logical HA host\n  int port = u.getPort();\n  if (port > 0 && port != 8020) {\n    path = new Path(\"hdfs://\" + u.getHost() + u.getPath()); // strip the port\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  fs = FileSystem.get(nameNodeUri, conf);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"logical (HA) namenode\")) {\n    URI stripped = URI.create(\"hdfs://\" + nameNodeUri.getHost() + \"/\");\n    fs = FileSystem.get(stripped, conf);\n  } else throw e;\n}","preventionTips":["Use port-less logical URIs (hdfs://nameservice/path) for HA clusters in all configs","Reject host:port templating in job frameworks when the host resolves as a nameservice","Remember port 8020 is the only tolerated port on a logical URI"],"tags":["hdfs","high-availability","uri","configuration","ha"],"backgroundTag":"ha-misconfiguration","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}