{"record":{"id":"b8a20c36d63cd642","repo":"quarkusio/quarkus","slug":"failed-to-start-spiffe-grpc-server-on-transport","errorCode":null,"errorMessage":"Failed to start SPIFFE gRPC server on ${transport}","messagePattern":"Failed to start SPIFFE gRPC server on (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/spiffe-client/deployment/src/main/java/io/quarkus/spiffe/client/deployment/SpiffeDevServicesProcessor.java","lineNumber":385,"sourceCode":"            listenGrpcServer();\n            if (transport != Transport.UNIX) {\n                grpcAddress = SocketAddress.inetSocketAddress(grpcServer.actualPort(), \"127.0.0.1\");\n            }\n            endpointSocket = transport == Transport.UNIX\n                    ? UNIX + grpcAddress.path()\n                    : \"tcp://127.0.0.1:\" + grpcServer.actualPort();\n        }\n\n        private void listenGrpcServer() {\n            grpcServer = vertx.createHttpServer(new HttpServerOptions());\n            try {\n                grpcServer.requestHandler(createGrpcServer())\n                        .listen(grpcAddress)\n                        .toCompletionStage()\n                        .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","sourceCodeStart":367,"sourceCodeEnd":403,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/spiffe-client/deployment/src/main/java/io/quarkus/spiffe/client/deployment/SpiffeDevServicesProcessor.java#L367-L403","documentation":"The SPIFFE dev service's Vert.x HTTP server hosting the gRPC handler fails to bind/listen on the resolved address (unix domain socket or 127.0.0.1:ephemeral) within the 20-second timeout. The failure is wrapped as RuntimeException 'Failed to start SPIFFE gRPC server on <transport>' with the underlying cause attached.","triggerScenarios":"listenGrpcServer() calls httpServer.listen(grpcAddress).get(20, TimeUnit.SECONDS); this throws when the port/socket cannot bind (address in use, permissions on the socket file), Vert.x fails to initialize, or the listen future doesn't complete within 20 seconds.","commonSituations":"Another process holding the same port when httpPort is pinned via devservices config; leftover stale unix socket file at the same path; slow/oversubscribed CI machines exceeding the 20s timeout; IPv4 loopback disabled in the container.","solutions":["Inspect the `Caused by:` for the real bind error; free the occupied port or remove stale socket files.","Omit the devservices port configuration to let it pick a free ephemeral port, or set a free quarkus.spiffe-client.devservices.http-port value.","Increase tolerance by retrying on slower CI, or switch transport to tcp to avoid unix socket pitfalls."],"exampleFix":"# before: fixed port that another process already holds\nquarkus.spiffe-client.devservices.http-port=15985\n\n# after: let the dev server choose a free ephemeral port\n# (remove the http-port line entirely)","handlingStrategy":"retry","validationCode":"// Before starting, check the port is free when a fixed http-port is configured:\ntry (var s = new java.net.ServerSocket(httpPort)) { /* free */ } catch (java.io.IOException e) {\n    throw new IllegalStateException(\"Port \" + httpPort + \" already in use\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    grpcServer.listen(grpcAddress).toCompletionStage().toCompletableFuture().get(20, TimeUnit.SECONDS);\n} catch (Exception e) {\n    LOG.error(\"gRPC dev server failed on \" + transport + \"; inspect Caused by (bind error vs timeout)\", e);\n}","preventionTips":["Let dev services pick ephemeral ports instead of fixed ones","Clean up crashed instances that leave stale sockets/ports bound","Run Quarkus test modules sequentially to avoid port conflicts"],"tags":["quarkus","spiffe","dev-services","grpc","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"}