{"record":{"id":"bbc990337c41743d","repo":"apache/hadoop","slug":"could-not-find-a-free-port-in-range","errorCode":null,"errorMessage":"Could not find a free port in ${range}","messagePattern":"Could not find a free port in (.+?)","errorType":"exception","errorClass":"BindException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java","lineNumber":747,"sourceCode":"      IntegerRanges range = null;\n      if (rangeConf != null) {\n        range = conf.getRange(rangeConf, \"\");\n      }\n      if (range == null || range.isEmpty() || (address.getPort() != 0)) {\n        socket.bind(address, backlog);\n      } else {\n        for (Integer port : range) {\n          if (socket.isBound()) break;\n          try {\n            InetSocketAddress temp = new InetSocketAddress(address.getAddress(),\n                port);\n            socket.bind(temp, backlog);\n          } catch(BindException e) {\n            //Ignored\n          }\n        }\n        if (!socket.isBound()) {\n          throw new BindException(\"Could not find a free port in \"+range);\n        }\n      }\n    } catch (SocketException e) {\n      throw NetUtils.wrapException(null,\n          0,\n          address.getHostName(),\n          address.getPort(), e);\n    }\n  }\n\n  @VisibleForTesting\n  int getPriorityLevel(Schedulable e) {\n    return callQueue.getPriorityLevel(e);\n  }\n\n  @VisibleForTesting\n  int getPriorityLevel(UserGroupInformation ugi) {\n    return callQueue.getPriorityLevel(ugi);","sourceCodeStart":729,"sourceCodeEnd":765,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java#L729-L765","documentation":"When an IPC Server is built with a port range configuration, the listener iterates the range calling socket.bind on each candidate and breaking on first success; if none of them bind it throws BindException(\"Could not find a free port in <range>\"). Every port in the configured range was already bound by another process. The outer catch wraps SocketException via NetUtils.wrapException.","triggerScenarios":"Starting a NameNode/DataNode/YARN/custom service with a port-range config while all candidate ports are occupied: colocated test JVMs, previous un-killed instances, containers sharing host networking, or a range overlapping the OS ephemeral port range.","commonSituations":"Dense CI machines running many miniclusters with narrow ranges; leftover listeners from crashed tests; misconfigured ranges too small for the number of services; containerized deployments sharing the host network namespace.","solutions":["Widen the configured port range, or clear it and use a single fixed port you have verified is free.","Find and stop the occupying processes: 'ss -ltnp' or 'lsof -i :<port>' over the range, then kill leftovers.","Give each service/test JVM a disjoint sub-range so concurrent starts cannot exhaust each other's candidates.","In tests, bind port 0 to let the OS assign an ephemeral port instead of using ranges."],"exampleFix":"# before — narrow range, often exhausted on shared hosts\nmy.rpc.port.range=50010-50012\n# after — disjoint, wider ranges per service\nsvcA.rpc.port.range=50010-50040\nsvcB.rpc.port.range=50050-50080\n# or in tests: fixed port 0 (ephemeral) avoids ranges entirely","handlingStrategy":"validation","validationCode":"static int findFreePort(List<Integer> candidates) throws IOException {\n  for (int p : candidates) {\n    try (ServerSocket s = new ServerSocket()) {\n      s.bind(new InetSocketAddress(p));\n      return p;\n    } catch (BindException ignored) {\n    }\n  }\n  throw new BindException(\"no free port among \" + candidates);\n}","typeGuard":null,"tryCatchPattern":"Catch BindException at server startup: report the configured range, list current listeners for those ports ('ss -ltn'), and abort startup with a clear message rather than retry-looping blind.","preventionTips":["Use port 0 in tests to get OS-assigned ephemeral ports.","Allocate disjoint port ranges per service on shared hosts and containers.","Stop listeners in test teardown (@AfterClass) so ranges are not exhausted across runs.","Check the configured range does not overlap /proc/sys/net/ipv4/ip_local_port_range."],"tags":["rpc","server","bind","port","network","configuration"],"backgroundTag":"port-already-in-use","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}