Implementation:SeleniumHQ Selenium PortProber

Knowledge Sources	SeleniumHQ_Selenium
Domains	WebDriver, Infrastructure
Last Updated	2026-02-12 00:00 GMT

Overview

PortProber is a utility class that finds free network ports and waits for ports to become available, while avoiding ephemeral port range conflicts.

Description

PortProber is a utility class in the org.openqa.selenium.net package designed to safely allocate free TCP ports for Selenium components. It detects the operating system's ephemeral port range (using LinuxEphemeralPortRangeDetector on Linux, OlderWindowsVersionEphemeralPortDetector on Windows XP, and FixedIANAPortRange on other systems) and selects random ports outside that range to minimize race conditions with the OS port allocator. The class also provides methods to verify port availability by attempting to bind on both localhost and 0.0.0.0, and to wait for a port to become connectable within a timeout period.

Usage

Use PortProber when starting Selenium servers, Grid nodes, or browser driver instances that need a dynamically assigned free port. It is also used to wait for a server to finish starting by polling until its port accepts connections.

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: java/src/org/openqa/selenium/net/PortProber.java

Signature

public class PortProber {

    public static final int HIGHEST_PORT = 65535;
    public static final int START_OF_USER_PORTS = 1024;

    public static int findFreePort()

    public static void waitForPortUp(int port, int timeout, TimeUnit unit)
}

Import

import org.openqa.selenium.net.PortProber;

I/O Contract

Method	Input	Output	Description
findFreePort()	none	int -- a free port number	Attempts up to 5 times to find a free port outside the ephemeral range. Validates the port is free on both localhost and 0.0.0.0. Throws RuntimeException if no free port is found.
waitForPortUp(int port, int timeout, TimeUnit unit)	port: port number to poll; timeout: maximum wait time; unit: time unit	void	Repeatedly attempts to connect to the specified port on localhost with a 1-second connect timeout. Returns when connection succeeds. Throws UncheckedIOException on unexpected I/O errors. Times out silently if the port never becomes available.

Constant	Value	Description
HIGHEST_PORT	65535	Maximum valid TCP port number
START_OF_USER_PORTS	1024	Start of non-privileged user port range

Usage Examples

import org.openqa.selenium.net.PortProber;
import java.util.concurrent.TimeUnit;

// Find a free port for a server
int port = PortProber.findFreePort();
System.out.println("Starting server on port: " + port);

// Wait for a server to start accepting connections
PortProber.waitForPortUp(port, 30, TimeUnit.SECONDS);

Related Pages

• SeleniumHQ_Selenium_NetworkUtils -- Network address resolution utility in the same package
• SeleniumHQ_Selenium_HostIdentifier -- Static host identification in the same package
• SeleniumHQ_Selenium_UrlChecker -- URL-level availability polling (complements port-level checks)