{"record":{"id":"4e09a000779f5ef2","repo":"apache/flink","slug":"could-not-find-a-free-permitted-port-on-the-machin","errorCode":null,"errorMessage":"Could not find a free permitted port on the machine.","messagePattern":"Could not find a free permitted port on the machine\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/util/NetUtils.java","lineNumber":206,"sourceCode":"     * @return A non-occupied port.\n     */\n    public static Port getAvailablePort() {\n        for (int i = 0; i < 50; i++) {\n            try (ServerSocket serverSocket = new ServerSocket(0)) {\n                int port = serverSocket.getLocalPort();\n                if (port != 0) {\n                    FileLock fileLock = new FileLock(NetUtils.class.getName() + port);\n                    if (fileLock.tryLock()) {\n                        return new Port(port, fileLock);\n                    } else {\n                        fileLock.unlockAndDestroy();\n                    }\n                }\n            } catch (IOException ignored) {\n            }\n        }\n\n        throw new RuntimeException(\"Could not find a free permitted port on the machine.\");\n    }\n\n    // ------------------------------------------------------------------------\n    //  Encoding of IP addresses for URLs\n    // ------------------------------------------------------------------------\n\n    /**\n     * Returns an address in a normalized format for Pekko. When an IPv6 address is specified, it\n     * normalizes the IPv6 address to avoid complications with the exact URL match policy of Pekko.\n     *\n     * @param host The hostname, IPv4 or IPv6 address\n     * @return host which will be normalized if it is an IPv6 address\n     */\n    public static String unresolvedHostToNormalizedString(String host) {\n        // Return loopback interface address if host is null\n        // This represents the behavior of {@code InetAddress.getByName } and RFC 3330\n        if (host == null) {\n            host = InetAddress.getLoopbackAddress().getHostAddress();","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/NetUtils.java#L188-L224","documentation":"NetUtils.getAvailablePortAddress (free-port allocation) probes candidate ports and guards each with a FileLock so concurrent Flink processes do not grab the same port; if every candidate is either unbindable or already file-locked, it gives up with this RuntimeException. Exhaustion usually means the environment restricts bindable ports or many JVMs are competing. It is a startup-time failure, not a data-path one.","triggerScenarios":"A configured port range whose ports are all taken or below the ephemeral range; dozens of parallel Flink test JVMs on one CI host leaving stale FileLocks in java.io.tmpdir; security policy preventing binding so the socket attempt always fails.","commonSituations":"CI machines running many tests in parallel; leftover lock files in /tmp after killed JVMs; Docker/Kubernetes network policies blocking binds; a copied port range config that does not fit the target host.","solutions":["Widen or change the port range configuration so allocation has candidates to try.","Clean stale lock files left by killed processes from the temp directory (FileLock names are NetUtils-classname + port).","Reduce the number of concurrently starting Flink processes on the host.","If binding is denied by the environment, run where bind(0) or the configured range is permitted."],"exampleFix":"// before\n// e.g. tests all using range 40000-40010 on a busy CI host\n\n// after\n// let the OS pick, or use a wider range\nNetUtils.Port p = NetUtils.getAvailablePortAddress(); // port 0 => OS-assigned","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (RuntimeException e) { if (e.getMessage().contains(\"free permitted port\")) { /* clean stale locks in tmpdir, widen range, retry once with a different range */ } }","preventionTips":["Use wide or OS-assigned (0) port ranges on shared CI hosts.","Clean up temp-dir lock files after killed JVMs.","Stagger parallel Flink process startups."],"tags":["network","ports","concurrency","environment","flink-core"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}