{"record":{"id":"fa623935a228b98d","repo":"apache/hadoop","slug":"unable-to-bind-on-specified-streaming-port-in-secu","errorCode":null,"errorMessage":"Unable to bind on specified streaming port in secure context. Needed {}, got {}","messagePattern":"Unable to bind on specified streaming port in secure context\\. Needed (.+?), got (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/SecureDataNodeStarter.java","lineNumber":142,"sourceCode":"        DFSConfigKeys.DFS_DATANODE_SOCKET_WRITE_TIMEOUT_KEY,\n        HdfsConstants.WRITE_TIMEOUT);\n    int backlogLength = conf.getInt(\n        CommonConfigurationKeysPublic.IPC_SERVER_LISTEN_QUEUE_SIZE_KEY,\n        CommonConfigurationKeysPublic.IPC_SERVER_LISTEN_QUEUE_SIZE_DEFAULT);\n\n    ServerSocket ss = (socketWriteTimeout > 0) ? \n        ServerSocketChannel.open().socket() : new ServerSocket();\n    try {\n      ss.bind(streamingAddr, backlogLength);\n    } catch (BindException e) {\n      BindException newBe = appendMessageToBindException(e,\n          streamingAddr.toString());\n      throw newBe;\n    }\n\n    // Check that we got the port we need\n    if (ss.getLocalPort() != streamingAddr.getPort()) {\n      throw new RuntimeException(\n          \"Unable to bind on specified streaming port in secure \"\n              + \"context. Needed \" + streamingAddr.getPort() + \", got \"\n              + ss.getLocalPort());\n    }\n    isRpcPrivileged = SecurityUtil.isPrivilegedPort(ss.getLocalPort());\n    System.err.println(\"Opened streaming server at \" + streamingAddr);\n\n    // Bind a port for the web server. The code intends to bind HTTP server to\n    // privileged port only, as the client can authenticate the server using\n    // certificates if they are communicating through SSL.\n    final ServerSocketChannel httpChannel;\n    if (policy.isHttpEnabled()) {\n      httpChannel = ServerSocketChannel.open();\n      InetSocketAddress infoSocAddr = DataNode.getInfoAddr(conf);\n      try {\n        httpChannel.socket().bind(infoSocAddr);\n      } catch (BindException e) {\n        BindException newBe = appendMessageToBindException(e,","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/SecureDataNodeStarter.java#L124-L160","documentation":"In secure (Kerberos + jsvc) startup, SecureDataNodeStarter binds the DataNode streaming socket itself so it can run privileged. After ss.bind(streamingAddr) succeeds, it verifies the kernel actually gave it the port requested; if the local port differs (typical when the configured port is 0, so the OS assigned an ephemeral port), it throws this RuntimeException because secure data transfer requires a fixed, known, often privileged port.","triggerScenarios":"jsvc secure startup with dfs.datanode.address resolving to port 0 (e.g. set to 0.0.0.0:0 or a hostname with :0), so bind() picks a random ephemeral port and ss.getLocalPort() != streamingAddr.getPort(). Also reachable with exotic socket/OS behavior, but port 0 is the practical trigger.","commonSituations":"Securing a cluster and enabling SASL data transfer (dfs.data.transfer.saslproperties.resolver.class) so the DN must start under jsvc, while dfs.datanode.address was left as/specified with port 0; port clashes that push admins to 'just use 0' on non-secure setups then enabling security; config drift after upgrade to 3.x default 9866.","solutions":["Set an explicit streaming port in hdfs-site.xml: dfs.datanode.address = 0.0.0.0:9866 (or your chosen fixed port), then restart the datanode under jsvc","Ensure that port is free and, if the deployment requires privileged ports, < 1024 so SecurityUtil.isPrivilegedPort() sees it as privileged","Keep dfs.datanode.address identical on all DNs so clients can address them consistently"],"exampleFix":"# before (hdfs-site.xml)\n<property><name>dfs.datanode.address</name><value>0.0.0.0:0</value></property>\n\n# after\n<property><name>dfs.datanode.address</name><value>0.0.0.0:9866</value></property>","handlingStrategy":"validation","validationCode":"import org.apache.hadoop.conf.Configuration;\nimport org.apache.hadoop.hdfs.DFSConfigKeys;\nimport java.net.InetSocketAddress;\nvoid assertFixedStreamingPort(Configuration conf) {\n  InetSocketAddress a = InetSocketAddress.createUnresolved(\n      conf.get(DFSConfigKeys.DFS_DATANODE_ADDRESS_KEY,\n               DFSConfigKeys.DFS_DATANODE_ADDRESS_DEFAULT),\n      -1 /* placeholder */);\n  // simpler: parse the port from the raw string\n  String v = conf.get(DFSConfigKeys.DFS_DATANODE_ADDRESS_KEY,\n                      DFSConfigKeys.DFS_DATANODE_ADDRESS_DEFAULT);\n  int port = Integer.parseInt(v.substring(v.lastIndexOf(':') + 1));\n  if (port == 0) throw new IllegalStateException(\n      \"dfs.datanode.address must use a fixed port in secure mode: \" + v);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never use port 0 for dfs.datanode.address when SASL/Kerberos data transfer is enabled","Validate all datanode listener ports (9866, 9864, 9865) in config linting before deploying with jsvc"],"tags":["hdfs","datanode","security","kerberos","jsvc","port-binding","startup"],"backgroundTag":"port-binding-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}