apache/hadoop · error · BindException

Could not find a free port in ${range}

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.

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)

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
• Got an IO exception
• Unknown method {} called on {} protocol.
• Unknown protocol: {}
• Unknown method ${methodName} called on ${connectionProtocolN

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