quarkusio/quarkus · error · IllegalArgumentException

gRPC client '${name}' cannot use both domain-socket and Stor

Error message

gRPC client '${name}' cannot use both domain-socket and Stork name resolver

What it means

Quarkus gRPC channels can target a Unix domain socket or use the Stork name resolver, but not both: Stork returns network service instances (host:port) while a domain-socket configuration pins the channel to a local Unix socket path. Channels.createChannel validates the combination up front and throws IllegalArgumentException when both domain-socket and name-resolver=stork are configured.

Source

Thrown at extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/supports/Channels.java:120

                boolean clientUsesTls = clientConfig.tlsConfigurationName().isPresent() || clientConfig.tls().enabled()
                        || (clientConfig.plainText().isPresent() && !clientConfig.plainText().get());
                ValueRegistry valueRegistry = container.instance(ValueRegistry.class).get();
                HttpServer httpServer = valueRegistry.get(HttpServer.HTTP_SERVER);
                int actualPort = clientUsesTls ? httpServer.getSecurePort() : httpServer.getPort();
                if (actualPort > 0) {
                    port = actualPort;
                } else {
                    port = clientUsesTls ? 8444 : 8081;
                }
            }
        }

        String nameResolver = clientConfig.nameResolver();

        boolean stork = Stork.STORK.equalsIgnoreCase(nameResolver);
        boolean useDomainSocket = clientConfig.domainSocket().isPresent();
        if (useDomainSocket && stork) {
            throw new IllegalArgumentException(
                    "gRPC client '" + name + "' cannot use both domain-socket and Stork name resolver");
        }

        String[] resolverSplit = nameResolver.split(":");
        String resolver = resolverSplit[0];

        // Client-side interceptors
        GrpcClientInterceptorContainer interceptorContainer = container
                .instance(GrpcClientInterceptorContainer.class).get();
        if (stork) {
            perClientInterceptors = new HashSet<>(perClientInterceptors);
            perClientInterceptors.add(VertxStorkMeasuringGrpcInterceptor.class.getName());
        }

        @SuppressWarnings("rawtypes")
        List<ChannelBuilderCustomizer> channelBuilderCustomizers = container
                .select(ChannelBuilderCustomizer.class, Any.Literal.INSTANCE)
                .stream()

View on GitHub (pinned to e1c734241f)

Solutions

Remove the quarkus.grpc.clients.<name>.domain-socket property when using Stork service discovery.
Or remove name-resolver=stork for that client if it must communicate over a Unix domain socket.
Check active Maven/Quarkus profiles so %dev (domain socket) and %prod (stork) settings don't collide.
Use Stork for discovery in remote environments and configure the domain socket only in local dev.

Example fix

// before
quarkus.grpc.clients.hello.domain-socket=/var/run/app.sock
quarkus.grpc.clients.hello.name-resolver=stork

// after
quarkus.grpc.clients.hello.name-resolver=stork
# domain-socket removed

Defensive patterns

Strategy: validation

Validate before calling

// validate client config before startup
String socket = config.getOptionalValue("quarkus.grpc.clients.hello.domain-socket", String.class).orElse(null);
String resolver = config.getOptionalValue("quarkus.grpc.clients.hello.name-resolver", String.class).orElse("");
if (socket != null && "stork".equalsIgnoreCase(resolver)) {
    throw new IllegalStateException("Client 'hello': drop domain-socket or name-resolver=stork");
}

Try / catch

try {
    channel = Channels.createChannel("hello", interceptors);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("domain-socket and Stork")) {
        throw new ConfigurationException("Remove either domain-socket or name-resolver=stork for client 'hello'", e);
    }
    throw e;
}

Prevention

Scope domain-socket config to the %dev profile and Stork config to %prod.
Document per-profile transport choices for each gRPC client.
Add config validation in a startup observer for mixed profiles.

When it happens

Trigger: quarkus.grpc.clients.<name>.domain-socket=<path> is set together with quarkus.grpc.clients.<name>.name-resolver=stork for the same client, so useDomainSocket && stork is true during channel creation.

Common situations: Copy-pasting a domain-socket config from a local-dev profile into a profile that also enables Stork service discovery; profiles (e.g. %prod stork, %dev domain-socket) merged so both keys end up active.

Related errors

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