{"record":{"id":"56d82e208267f71b","repo":"apache/pulsar","slug":"failed-to-start-http-server-on-ports-ports","errorCode":null,"errorMessage":"Failed to start HTTP server on ports ${ports}","messagePattern":"Failed to start HTTP server on ports (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/WebServer.java","lineNumber":381,"sourceCode":"                .findFirst().ifPresent(c -> {\n                        WebServer.this.externalServicePort = ((ServerConnector) c).getPort();\n                    });\n\n            // server reports URI of first servlet, we want to strip that path off\n            URI reportedURI = server.getURI();\n            serviceURI = new URI(reportedURI.getScheme(),\n                                 null,\n                                 reportedURI.getHost(),\n                                 reportedURI.getPort(),\n                                 null, null, null);\n        } catch (Exception e) {\n            List<Integer> ports = new ArrayList<>();\n            for (Connector c : server.getConnectors()) {\n                if (c instanceof ServerConnector) {\n                    ports.add(((ServerConnector) c).getPort());\n                }\n            }\n            throw new IOException(\"Failed to start HTTP server on ports \" + ports, e);\n        }\n\n        log.info()\n                .attr(\"getServiceUri\", getServiceUri())\n                .log(\"Server started at end point\");\n    }\n\n    public void stop() throws Exception {\n        // PIP-478: dispose the TLS factory subscription and close the factory, if the new path was used.\n        releaseTlsResources();\n        server.stop();\n        webServiceExecutor.stop();\n        log.info(\"Server stopped successfully\");\n    }\n\n    public boolean isStarted() {\n        return server.isStarted();\n    }","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/WebServer.java#L363-L399","documentation":"WebServer.start boots the embedded Jetty server; if server.start() throws, it collects the ports of the configured connectors and wraps the failure in an IOException listing them. This tells the operator which HTTP/HTTPS ports the web console/REST endpoints failed to bind while the root cause (usually BindException) is attached as the cause.","triggerScenarios":"Calling webServer.start() when the Jetty connector cannot bind: web service port already in use by another process, configured bindAddress unavailable, insufficient permission for a privileged port, or TLS configuration failure on the SSL connector.","commonSituations":"Broker/proxy web port 8080 already used by another service (common collision with other Java apps); stale proxy from a previous run still holding the port; Kubernetes/Docker port conflicts; misconfigured bindAddress; invalid keystore config for the TLS connector.","solutions":["Inspect the cause (usually BindException) and free the listed ports or change the web service port in config","Ensure only one instance runs on the host — stop the stale process holding the port","Verify the bindAddress is valid for the machine and ports are unprivileged or you have permission","If TLS connector is involved, validate the TLS/keystore configuration before restarting"],"exampleFix":"// before\nwebServicePort=8080  # already in use\n\n// after\nwebServicePort=8081","handlingStrategy":"validation","validationCode":"int webPort = webServer.getServicePort();\ntry (ServerSocket ss = new ServerSocket()) {\n    ss.bind(new InetSocketAddress(webPort));\n} catch (IOException e) {\n    throw new IllegalStateException(\"Web port \" + webPort + \" unavailable before WebServer.start(): \" + e.getMessage());\n}","typeGuard":"boolean webPortAvailable(int port) {\n    try (ServerSocket ss = new ServerSocket(port)) {\n        return true;\n    } catch (IOException e) {\n        return false;\n    }\n}","tryCatchPattern":"try {\n    webServer.start();\n} catch (IOException e) {\n    if (e.getCause() != null && e.getCause().getClass().getSimpleName().contains(\"BindException\")) {\n        LOG.error(\"Jetty could not bind web ports ({}): {}\", e.getMessage(), e.getCause().getMessage());\n    }\n    throw e;\n}","preventionTips":["Pre-check web service ports for availability in deployment scripts","Avoid the common 8080/8443 collisions with other Java services on the same host","Validate TLS/keystore settings before enabling the TLS connector","Stop leftover processes from previous runs before restart"],"tags":["pulsar-proxy","jetty","network","port-in-use","startup"],"backgroundTag":"address-already-in-use","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}