alibaba/arthas · error · IllegalStateException

Could not find an available tcp port in the range [%d, %d] a

Error message

Could not find an available tcp port in the range [%d, %d] after %d attempts

What it means

Thrown by SocketUtils.findAvailablePort when every port in [minPort, maxPort] has been probed (searchCounter exceeds portRange) and none was reported available by isTcpPortAvailable. The loop picks pseudo-random candidate ports; once it has tried more candidates than the size of the range without success, it gives up. This is a Spring-derived utility, so the message format is fixed.

Source

Thrown at common/src/main/java/com/taobao/arthas/common/SocketUtils.java:172

    }

    /**
     * Find an available port for this {@code SocketType}, randomly selected from
     * the range [{@code minPort}, {@code maxPort}].
     * 
     * @param minPort the minimum port number
     * @param maxPort the maximum port number
     * @return an available port number for this socket type
     * @throws IllegalStateException if no available port could be found
     */
    private static int findAvailablePort(int minPort, int maxPort) {

        int portRange = maxPort - minPort;
        int candidatePort;
        int searchCounter = 0;
        do {
            if (searchCounter > portRange) {
                throw new IllegalStateException(
                        String.format("Could not find an available tcp port in the range [%d, %d] after %d attempts",
                                minPort, maxPort, searchCounter));
            }
            candidatePort = findRandomPort(minPort, maxPort);
            searchCounter++;
        } while (!isTcpPortAvailable(candidatePort));

        return candidatePort;
    }

    /**
     * Find a pseudo-random port number within the range [{@code minPort},
     * {@code maxPort}].
     * 
     * @param minPort the minimum port number
     * @param maxPort the maximum port number
     * @return a random port number within the specified range
     */

View on GitHub (pinned to 21cf2e9ba5)

Solutions

Widen the port range, or let Arthas pick from the default wide ephemeral range.
Free up ports occupied by orphaned Arthas/tunnel processes (ps/lsof and kill the stale listeners).
Reduce parallelism so fewer processes contend for the same range simultaneously.
If in a container, ensure enough host ports are published/available for the requested range.

Example fix

// before
int port = SocketUtils.findAvailableTcpPort(3658, 3660); // 3-port window, often exhausted

// after
int port = SocketUtils.findAvailableTcpPort(3658, 3790); // wider window

Defensive patterns

Strategy: retry

Validate before calling

int min=3658, max=3790;
if (max - min < 1) { /* range too small; widen or fail early */ }

Try / catch

try {
    int port = SocketUtils.findAvailableTcpPort(min, max);
} catch (IllegalStateException e) {
    // widen range, clean stale listeners, or back off and retry once
}

Prevention

Use a wide port range for tests/services to reduce collisions.
Tear down listeners in @After to free ports between test runs.
Monitor and kill orphaned Arthas/tunnel processes holding ports.

When it happens

Trigger: Call findAvailablePort(minPort, maxPort) (or a public wrapper like findAvailableTcpPort) where the entire range is occupied or unbindable — e.g. a tiny range with all ports already bound, or a large range with no free ephemeral ports on a heavily loaded host.

Common situations: Tight port range in tests (e.g. findAvailableTcpPort(8080, 8081)); many test processes competing for the same small range; a host where most ports are in use by other services; binding restrictions (e.g. containers with limited published ports); transient port-in-use races between isTcpPortAvailable and actual bind.

Related errors

AI-assisted analysis of alibaba/arthas@21cf2e9ba5 (2026-08-14). Data as JSON: /api/errors/3fd293313b37b060. Report an issue: GitHub.