{"record":{"id":"7b3b04550b58b574","repo":"quarkusio/quarkus","slug":"failed-to-bind-virtual-http","errorCode":null,"errorMessage":"failed to bind virtual http","messagePattern":"failed to bind virtual http","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/VertxHttpRecorder.java","lineNumber":1732,"sourceCode":"                        ch.pipeline().addLast(\"handler\", handler);\n                    }\n\n                    private static HttpServerOptions createVirtualHttpServerOptions() {\n                        var result = new HttpServerOptions();\n                        Optional<MemorySize> maybeMaxHeadersSize = ConfigProvider.getConfig()\n                                .getOptionalValue(\"quarkus.http.limits.max-header-size\", MemorySize.class);\n                        if (maybeMaxHeadersSize.isPresent()) {\n                            result.setMaxHeaderSize(maybeMaxHeadersSize.get().asIntValue());\n                        }\n                        return result;\n                    }\n                });\n\n        // Start the server.\n        try {\n            virtualBootstrapChannel = virtualBootstrap.bind(VIRTUAL_HTTP).sync();\n        } catch (InterruptedException e) {\n            throw new RuntimeException(\"failed to bind virtual http\");\n        }\n\n    }\n\n    public static Handler<HttpServerRequest> getRootHandler() {\n        return ACTUAL_ROOT;\n    }\n\n    /**\n     * used in the live reload handler to make sure the application has not been changed by another source (e.g. reactive\n     * messaging)\n     */\n    public static Object getCurrentApplicationState() {\n        return rootHandler;\n    }\n\n    private static boolean isGrpc(RoutingContext rc) {\n        HttpServerRequest request = rc.request();","sourceCodeStart":1714,"sourceCodeEnd":1750,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/VertxHttpRecorder.java#L1714-L1750","documentation":"Quarkus failed to start the internal virtual HTTP bootstrap server used by the Vert.x HTTP extension (e.g. dev-mode virtual hosting / management routing). The Netty bootstrap bind() to the VIRTUAL_HTTP socket threw, most often because the port is already in use or the network interface does not exist, and the wrapping RuntimeException hides the original cause (it is not passed as cause).","triggerScenarios":"VertxHttpRecorder.startServerAfterFailedLaunch/dev startup calls virtualBootstrap.bind(VIRTUAL_HTTP).sync() and the bind fails: port already occupied, address/interface not resolvable, or permission denied on a privileged port.","commonSituations":"Another Quarkus instance or process (often a stale dev-mode process) is still holding the virtual http port; quarkus.http.* / management port misconfigured in application.properties; running in a container or CI where the configured bind address is unavailable; the thread was interrupted during bind.","solutions":["Find and kill the process holding the virtual HTTP port (lsof -i :<port> / netstat -ano), often a leftover Quarkus dev process.","Check quarkus.http.port / quarkus.management.port and quarkus.http.host in application.properties for conflicts or invalid interfaces.","Set the port to 0 (random) in dev mode to dodge conflicts.","Re-run the build with more logging to surface the suppressed cause, since this RuntimeException does not chain the original exception.","Restart the machine/container if a zombie process cannot be found."],"exampleFix":"// before (application.properties)\nquarkus.http.port=8080\n// after\nquarkus.http.port=0   # let the OS pick a free port in dev mode","handlingStrategy":"validation","validationCode":"int port = Integer.parseInt(config.httpPort());\ntry (ServerSocket s = new ServerSocket()) {\n    s.bind(new InetSocketAddress(config.httpHost(), port)); // throws if occupied\n} catch (BindException e) {\n    throw new IllegalStateException(\"Port \" + port + \" already in use — stop the other process or use port 0\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use quarkus.http.port=0 in dev/CI so a free port is auto-picked","Add a pre-build check that kills stale quarkus:dev processes","Never hardcode the same port for app and management interfaces","Monitor for TIME_WAIT/zombie sockets in shared CI runners"],"tags":["quarkus","vertx-http","bind","port-conflict","startup"],"backgroundTag":"address-already-in-use","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}