{"record":{"id":"7d8af7184fa3e5be","repo":"SonarSource/sonarqube","slug":"fail-to-find-an-available-port-on","errorCode":null,"errorMessage":"Fail to find an available port on ","messagePattern":"Fail to find an available port on ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"server/sonar-process/src/main/java/org/sonar/process/NetworkUtilsImpl.java","lineNumber":80,"sourceCode":"      .map(t -> getNextAvailablePort(t, PortAllocator.INSTANCE))\n      .orElseThrow(() -> new IllegalArgumentException(format(\"Can not resolve address %s\", hostOrAddress))));\n  }\n\n  /**\n   * Warning - the allocated ports are kept in memory and are never clean-up. Besides the memory consumption,\n   * that means that ports already allocated are never freed. As a consequence\n   * no more than ~64512 calls to this method are allowed.\n   */\n  @VisibleForTesting\n  static int getNextAvailablePort(InetAddress address, PortAllocator portAllocator) {\n    for (int i = 0; i < PORT_MAX_TRIES; i++) {\n      int port = portAllocator.getAvailable(address);\n      if (isValidPort(port)) {\n        PORTS_ALREADY_ALLOCATED.add(port);\n        return port;\n      }\n    }\n    throw new IllegalStateException(\"Fail to find an available port on \" + address);\n  }\n\n  private static boolean isValidPort(int port) {\n    return port > 1023 && !PORTS_ALREADY_ALLOCATED.contains(port);\n  }\n\n  static class PortAllocator {\n\n    private static final PortAllocator INSTANCE = new PortAllocator();\n\n    int getAvailable(InetAddress address) {\n      try (ServerSocket socket = new ServerSocket(0, 50, address)) {\n        return socket.getLocalPort();\n      } catch (IOException e) {\n        throw new IllegalStateException(\"Fail to find an available port on \" + address, e);\n      }\n    }\n  }","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-process/src/main/java/org/sonar/process/NetworkUtilsImpl.java#L62-L98","documentation":"getNextAvailablePort tries portAllocator.getAvailable for candidate ports and gives up if none yields a valid free port, throwing IllegalStateException. It means no usable (non-privileged, unallocated) port could be found for the address.","triggerScenarios":"Repeated calls exhausting the allocator's candidates; isValidPort rejecting ports <=1023 or already allocated by this process; the OS denying socket binds.","commonSituations":"Long-lived process allocating many ports over time; restricted environments limiting ephemeral ports; all candidates in PORTS_ALREADY_ALLOCATED.","solutions":["Check the process for leaked sockets/ports that stay in PORTS_ALREADY_ALLOCATED","Restart the process to clear the in-memory allocation cache","Verify the OS allows binding on the given address and ephemeral port range","Inspect the wrapped cause from the inner allocator for bind failures"],"exampleFix":"null","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  int port = networkUtils.getNextAvailablePort(addr);\n} catch (IllegalStateException e) {\n  LOGGER.error(\"No available port; check leaked sockets and port range\", e);\n}","preventionTips":["Close sockets promptly to avoid leaks in the allocation cache","Restart long-running processes that allocate many ports","Verify the OS ephemeral port range is not exhausted (ss -s / netstat)"],"tags":["network","ports","socket"],"backgroundTag":"address-already-in-use","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}