{"record":{"id":"65f232e0fc0eeaa0","repo":"quarkusio/quarkus","slug":"failed-to-start-spiffe-http-server","errorCode":null,"errorMessage":"Failed to start SPIFFE HTTP server","messagePattern":"Failed to start SPIFFE HTTP server","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/spiffe-client/deployment/src/main/java/io/quarkus/spiffe/client/deployment/SpiffeDevServicesProcessor.java","lineNumber":400,"sourceCode":"                        .toCompletableFuture()\n                        .get(20, TimeUnit.SECONDS);\n            } catch (Exception e) {\n                throw new RuntimeException(\"Failed to start SPIFFE gRPC server on \" + transport, e);\n            }\n        }\n\n        private void startHttpServer() {\n            httpServer = vertx.createHttpServer(new HttpServerOptions().setPort(httpPort));\n            try {\n                httpServer.requestHandler(this::handleHttpRequest)\n                        .listen(SocketAddress.inetSocketAddress(httpPort, \"127.0.0.1\"))\n                        .toCompletionStage()\n                        .toCompletableFuture()\n                        .get(20, TimeUnit.SECONDS);\n                LOG.debugf(\"Started SPIFFE HTTP server on port %s\", httpServer.actualPort());\n            } catch (Exception e) {\n                errorMessages.add(\"Failed to start SPIFFE HTTP server: \" + e.getMessage());\n                throw new RuntimeException(\"Failed to start SPIFFE HTTP server\", e);\n            }\n        }\n\n        @Override\n        public String getConnectionInfo() {\n            return endpointSocket;\n        }\n\n        @Override\n        public String getContainerId() {\n            return null;\n        }\n    }\n\n    static final class SpiffeDevServicesEnabled implements BooleanSupplier {\n\n        private final boolean enabled;\n","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/spiffe-client/deployment/src/main/java/io/quarkus/spiffe/client/deployment/SpiffeDevServicesProcessor.java#L382-L418","documentation":"Companion to the gRPC failure: the SPIFFE dev HTTP server (used to serve JWKS and related endpoints) fails to bind or complete its listen within 20 seconds. startHttpServer() wraps the exception as RuntimeException 'Failed to start SPIFFE HTTP server' and records the cause message in errorMessages.","triggerScenarios":"startHttpServer() creates a Vert.x HttpServer on the configured httpPort and awaits listen(...).get(20, TimeUnit.SECONDS); failure occurs when the port is already bound (BindException), permissions block binding, or the future times out.","commonSituations":"Port conflicts with other dev services or a previously crashed instance still holding the port; running two Quarkus dev apps concurrently with the same fixed devservices port; firewall/SELinux restrictions on loopback ports.","solutions":["Check `Caused by:` for BindException; kill the process holding the port (lsof -i :<port> / netstat).","Remove any fixed quarkus.spiffe-client.devservices.http-port so an ephemeral port is used.","Address 'Address already in use' by setting SO_REUSEPORT-capable alternatives or just changing the port; on CI, stagger parallel module runs (Quarkus does not support parallel test modules)."],"exampleFix":"# before\nquarkus.spiffe-client.devservices.http-port=15986\n\n# after: ephemeral port (key removed); read the actual port from DevServices logs\n# quarkus.spiffe-client.devservices.http-port=<unset>","handlingStrategy":"retry","validationCode":"try (var s = new java.net.ServerSocket(httpPort)) { /* port free */ }\ncatch (java.io.IOException e) { throw new IllegalStateException(\"http-port \" + httpPort + \" occupied\"); }","typeGuard":null,"tryCatchPattern":"try {\n    httpServer.listen(httpPort).toCompletionStage().toCompletableFuture().get(20, TimeUnit.SECONDS);\n} catch (Exception e) {\n    LOG.error(\"SPIFFE HTTP dev server failed; check Caused by for BindException/timeout\", e);\n}","preventionTips":["Remove fixed devservices port settings in shared config","Kill leftover processes after crashed dev runs before restarting","Avoid parallel Quarkus test module execution (port conflicts)"],"tags":["quarkus","spiffe","dev-services","http","port-bind"],"backgroundTag":"port-already-in-use","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}