{"record":{"id":"a4db15ef8474ecb8","repo":"apache/hadoop","slug":"free-ports-could-not-be-acquired","errorCode":null,"errorMessage":"{} free ports could not be acquired.","messagePattern":"(.+?) free ports could not be acquired\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetUtils.java","lineNumber":1173,"sourceCode":"   *\n   * @param numOfPorts Number of free ports to acquire.\n   * @return Free ports for binding a local socket.\n   */\n  public static Set<Integer> getFreeSocketPorts(int numOfPorts) {\n    Preconditions.checkArgument(numOfPorts > 0 && numOfPorts <= 25,\n        \"Valid range for num of ports is between 0 and 26\");\n    final Set<Integer> freePorts = new HashSet<>(numOfPorts);\n    for (int i = 0; i < numOfPorts * 5; i++) {\n      int port = getFreeSocketPort();\n      if (port == 0) {\n        continue;\n      }\n      freePorts.add(port);\n      if (freePorts.size() == numOfPorts) {\n        return freePorts;\n      }\n    }\n    throw new IllegalStateException(numOfPorts + \" free ports could not be acquired.\");\n  }\n\n  /**\n   * Return an @{@link InetAddress} to bind to. If bindWildCardAddress is true\n   * then returns null.\n   *\n   * @param localAddr local addr.\n   * @param bindWildCardAddress bind wildcard address.\n   * @return InetAddress\n   */\n  public static InetAddress bindToLocalAddress(InetAddress localAddr, boolean\n      bindWildCardAddress) {\n    if (!bindWildCardAddress) {\n      return localAddr;\n    }\n    return null;\n  }\n}","sourceCodeStart":1155,"sourceCodeEnd":1191,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/net/NetUtils.java#L1155-L1191","documentation":"IllegalStateException from NetUtils.getFreeSocketPorts(numOfPorts) when, after up to numOfPorts*5 attempts, fewer than numOfPorts distinct non-zero free ports were collected. Each attempt opens a ServerSocket(0), records the port, and closes it — ports can repeat (deduped by the Set) or come back 0 on failure, so a heavily loaded host or a nearly exhausted ephemeral range starves the collection. numOfPorts must also satisfy 0 < numOfPorts <= 25 or Preconditions fails first with a different message.","triggerScenarios":"Requesting many ports (e.g., 25) on a machine whose ephemeral range is mostly occupied; concurrent callers racing for the same few free ports so duplicates dominate the 5x attempts; ulimit/file-descriptor pressure making ServerSocket(0) fail repeatedly (port returns 0).","commonSituations":"Integration tests spawning many services in parallel on CI boxes; containers with tiny ip_local_port_range; fd exhaustion (ulimit -n) causing repeated bind failures; requesting ports while a stress test holds thousands of connections.","solutions":["Reduce numOfPorts or run fewer concurrent port-grabbing processes","Widen the ephemeral range / raise fd limits on the host: sysctl net.ipv4.ip_local_port_range, ulimit -n","Retry with backoff — port availability is transient; or fall back to acquiring ports one at a time as needed instead of in bulk","Check for fd leaks (lsof | wc -l) if ServerSocket(0) keeps failing"],"exampleFix":"// before\nSet<Integer> ports = NetUtils.getFreeSocketPorts(25); // loaded CI box -> IllegalStateException: 25 free ports could not be acquired.\n\n// after\nSet<Integer> ports = NetUtils.getFreeSocketPorts(5); // fewer ports per run,\n// plus raise limits: sysctl -w net.ipv4.ip_local_port_range=\"1024 65535\"; ulimit -n 65536","handlingStrategy":"retry","validationCode":"if (numOfPorts <= 0 || numOfPorts > 25) throw new IllegalArgumentException(\"numOfPorts must be in (0,25]\");\nlong fdUse = ...; // optional: check ulimit / ephemeral range before bulk requests","typeGuard":null,"tryCatchPattern":"catch (IllegalStateException e) { /* 'N free ports could not be acquired.' */ back off and retry with the same or smaller count; if persistent, widen ip_local_port_range / raise fd limit; }","preventionTips":["Request only as many ports as needed and use them immediately (they are not reserved)","On loaded CI boxes, serialize port-hungry tests or lower parallelism","Tune net.ipv4.ip_local_port_range and ulimit -n on hosts that run many socket-bound services"],"tags":["port","ephemeral-port","resource-exhaustion","testing","hadoop-common"],"backgroundTag":"port-exhaustion","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}