apache/hadoop · error · BindException

Could not find a free port in

Error message

Could not find a free port in ${range}

What it means

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.

Solutions

1. Widen the configured port range, or clear it and use a single fixed port you have verified is free.
2. Find and stop the occupying processes: 'ss -ltnp' or 'lsof -i :<port>' over the range, then kill leftovers.
3. Give each service/test JVM a disjoint sub-range so concurrent starts cannot exhaust each other's candidates.
4. In tests, bind port 0 to let the OS assign an ephemeral port instead of using ranges.

Example fix

# before — narrow range, often exhausted on shared hosts
my.rpc.port.range=50010-50012
# after — disjoint, wider ranges per service
svcA.rpc.port.range=50010-50040
svcB.rpc.port.range=50050-50080
# or in tests: fixed port 0 (ephemeral) avoids ranges entirely

static int findFreePort(List<Integer> candidates) throws IOException {
  for (int p : candidates) {
    try (ServerSocket s = new ServerSocket()) {
      s.bind(new InetSocketAddress(p));
      return p;
    } catch (BindException ignored) {
    }
  }
  throw new BindException("no free port among " + candidates);
}

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• conf is not set
• Error connecting to file system
• Error creating connection
• Got an IO exception
• instance is not set

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

Appendix: source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/Server.java:747

      IntegerRanges range = null;
      if (rangeConf != null) {
        range = conf.getRange(rangeConf, "");
      }
      if (range == null || range.isEmpty() || (address.getPort() != 0)) {
        socket.bind(address, backlog);
      } else {
        for (Integer port : range) {
          if (socket.isBound()) break;
          try {
            InetSocketAddress temp = new InetSocketAddress(address.getAddress(),
                port);
            socket.bind(temp, backlog);
          } catch(BindException e) {
            //Ignored
          }
        }
        if (!socket.isBound()) {
          throw new BindException("Could not find a free port in "+range);
        }
      }
    } catch (SocketException e) {
      throw NetUtils.wrapException(null,
          0,
          address.getHostName(),
          address.getPort(), e);
    }
  }

  @VisibleForTesting
  int getPriorityLevel(Schedulable e) {
    return callQueue.getPriorityLevel(e);
  }

  @VisibleForTesting
  int getPriorityLevel(UserGroupInformation ugi) {
    return callQueue.getPriorityLevel(ugi);

View on GitHub (pinned to 2add963021)