{"record":{"id":"3fd293313b37b060","repo":"alibaba/arthas","slug":"could-not-find-an-available-tcp-port-in-the-range","errorCode":null,"errorMessage":"Could not find an available tcp port in the range [%d, %d] after %d attempts","messagePattern":"Could not find an available tcp port in the range \\[(.+?), (.+?)\\] after (.+?) attempts","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/com/taobao/arthas/common/SocketUtils.java","lineNumber":172,"sourceCode":"    }\n\n    /**\n     * Find an available port for this {@code SocketType}, randomly selected from\n     * the range [{@code minPort}, {@code maxPort}].\n     * \n     * @param minPort the minimum port number\n     * @param maxPort the maximum port number\n     * @return an available port number for this socket type\n     * @throws IllegalStateException if no available port could be found\n     */\n    private static int findAvailablePort(int minPort, int maxPort) {\n\n        int portRange = maxPort - minPort;\n        int candidatePort;\n        int searchCounter = 0;\n        do {\n            if (searchCounter > portRange) {\n                throw new IllegalStateException(\n                        String.format(\"Could not find an available tcp port in the range [%d, %d] after %d attempts\",\n                                minPort, maxPort, searchCounter));\n            }\n            candidatePort = findRandomPort(minPort, maxPort);\n            searchCounter++;\n        } while (!isTcpPortAvailable(candidatePort));\n\n        return candidatePort;\n    }\n\n    /**\n     * Find a pseudo-random port number within the range [{@code minPort},\n     * {@code maxPort}].\n     * \n     * @param minPort the minimum port number\n     * @param maxPort the maximum port number\n     * @return a random port number within the specified range\n     */","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/alibaba/arthas/blob/21cf2e9ba52b305290be7223b980ff504bb9cb5b/common/src/main/java/com/taobao/arthas/common/SocketUtils.java#L154-L190","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nint port = SocketUtils.findAvailableTcpPort(3658, 3660); // 3-port window, often exhausted\n\n// after\nint port = SocketUtils.findAvailableTcpPort(3658, 3790); // wider window","handlingStrategy":"retry","validationCode":"int min=3658, max=3790;\nif (max - min < 1) { /* range too small; widen or fail early */ }","typeGuard":null,"tryCatchPattern":"try {\n    int port = SocketUtils.findAvailableTcpPort(min, max);\n} catch (IllegalStateException e) {\n    // widen range, clean stale listeners, or back off and retry once\n}","preventionTips":["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."],"tags":["network","tcp","port-allocation","configuration"],"backgroundTag":null,"analyzedSha":"21cf2e9ba52b305290be7223b980ff504bb9cb5b","analyzedAt":"2026-08-14T00:57:07.243Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}