quarkusio/quarkus · error · RuntimeException

Failed to start SPIFFE gRPC server on ${transport}

Error message

Failed to start SPIFFE gRPC server on ${transport}

What it means

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.

Source

Thrown at extensions/spiffe-client/deployment/src/main/java/io/quarkus/spiffe/client/deployment/SpiffeDevServicesProcessor.java:385

            listenGrpcServer();
            if (transport != Transport.UNIX) {
                grpcAddress = SocketAddress.inetSocketAddress(grpcServer.actualPort(), "127.0.0.1");
            }
            endpointSocket = transport == Transport.UNIX
                    ? UNIX + grpcAddress.path()
                    : "tcp://127.0.0.1:" + grpcServer.actualPort();
        }

        private void listenGrpcServer() {
            grpcServer = vertx.createHttpServer(new HttpServerOptions());
            try {
                grpcServer.requestHandler(createGrpcServer())
                        .listen(grpcAddress)
                        .toCompletionStage()
                        .toCompletableFuture()
                        .get(20, TimeUnit.SECONDS);
            } catch (Exception e) {
                throw new RuntimeException("Failed to start SPIFFE gRPC server on " + transport, e);
            }
        }

        private void startHttpServer() {
            httpServer = vertx.createHttpServer(new HttpServerOptions().setPort(httpPort));
            try {
                httpServer.requestHandler(this::handleHttpRequest)
                        .listen(SocketAddress.inetSocketAddress(httpPort, "127.0.0.1"))
                        .toCompletionStage()
                        .toCompletableFuture()
                        .get(20, TimeUnit.SECONDS);
                LOG.debugf("Started SPIFFE HTTP server on port %s", httpServer.actualPort());
            } catch (Exception e) {
                errorMessages.add("Failed to start SPIFFE HTTP server: " + e.getMessage());
                throw new RuntimeException("Failed to start SPIFFE HTTP server", e);
            }
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Inspect the `Caused by:` for the real bind error; free the occupied port or remove stale socket files.
2. Omit the devservices port configuration to let it pick a free ephemeral port, or set a free quarkus.spiffe-client.devservices.http-port value.
3. Increase tolerance by retrying on slower CI, or switch transport to tcp to avoid unix socket pitfalls.

Example fix

# before: fixed port that another process already holds
quarkus.spiffe-client.devservices.http-port=15985

# after: let the dev server choose a free ephemeral port
# (remove the http-port line entirely)

// Before starting, check the port is free when a fixed http-port is configured:
try (var s = new java.net.ServerSocket(httpPort)) { /* free */ } catch (java.io.IOException e) {
    throw new IllegalStateException("Port " + httpPort + " already in use");
}

try {
    grpcServer.listen(grpcAddress).toCompletionStage().toCompletableFuture().get(20, TimeUnit.SECONDS);
} catch (Exception e) {
    LOG.error("gRPC dev server failed on " + transport + "; inspect Caused by (bind error vs timeout)", e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to start SPIFFE HTTP server
• The SPIFFE client extension does not support unix transport
• Failed to generate EC P-256 signing key
• Failed to create temp socket path
• Dev services for ${request.getName()} requires a startable s

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b8a20c36d63cd642. Report an issue: GitHub.