quarkusio/quarkus · error · IllegalStateException

Failed to determine working socket addresses for service-nam

Error message

Failed to determine working socket addresses for service-name: ${serviceName}

What it means

StorkGrpcChannel.checkSocketAddress selects an instance from Stork service discovery and tries to derive usable gRPC socket addresses from it. When the selected Stork ServiceInstance yields no working socket address, the instance and its cached channel are evicted and an IllegalStateException is thrown, because gRPC cannot connect without an IP:port (or domain socket) target.

Source

Thrown at extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/stork/StorkGrpcChannel.java:211

    private void checkSocketAddress(Context context) {
        ServiceInstance instance = context.instance;
        Set<InetSocketAddress> socketAddresses = new HashSet<>();
        try {
            for (InetAddress inetAddress : InetAddress.getAllByName(instance.getHost())) {
                socketAddresses.add(new InetSocketAddress(inetAddress, instance.getPort()));
            }
        } catch (UnknownHostException e) {
            log.warn("Ignoring wrong host: '{}' for service name '{}'", instance.getHost(), serviceName, e);
        }

        if (!socketAddresses.isEmpty()) {
            context.address = socketAddresses.iterator().next(); // pick first
        } else {
            long serviceId = instance.getId();
            services.remove(serviceId);
            channels.remove(serviceId);
            throw new IllegalStateException("Failed to determine working socket addresses for service-name: " + serviceName);
        }
    }

    private static class StorkDelayedClientCall<RequestT, ResponseT> extends DelayedClientCall<RequestT, ResponseT> {
        public StorkDelayedClientCall(Executor callExecutor, ScheduledExecutorService scheduler, @Nullable Deadline deadline) {
            super(callExecutor, scheduler, deadline);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the Stork discovery config: ensure address-list entries are host:port and the port is the gRPC server port.
2. Verify the discovered instance is healthy and registered with an address + port (inspect Consul/K8s registry).
3. Fix DNS resolution inside the runtime environment (container networking, search domains).
4. Retain retries: the error already evicts the bad instance; ensure your call path retries the next Stork instance (set quarkus.grpc.clients.<name>.retry or application-level retry).

Example fix

// before
quarkus.stork.hello.service-discovery.address-list=my-service

// after
quarkus.stork.hello.service-discovery.address-list=my-service:9000

// pre-flight: ensure discovery returns instances with usable addresses
ServiceInstance si = Stork.getInstance().getService("hello")
    .getInstances().await().indefinitely().stream().findFirst().orElseThrow();
if (si.getAddress() == null || si.getPort() <= 0) {
    throw new IllegalStateException("Stork instance has no usable host:port");
}

try {
    return stub.sayHello(req).await(indefinitely());
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("working socket addresses")) {
        // instance evicted by the channel; retry picks the next Stork instance
        return retryWithBackoff(() -> stub.sayHello(req), 3);
    }
    throw e;
}

When it happens

Trigger: Stork service discovery returned a ServiceInstance whose address/port is absent, empty, or not expressible as a socket address (e.g. discovery type returns metadata-only instances, wrong port config, or a hostname that fails InetSocketAddress resolution), leaving socketAddresses empty in checkSocketAddress.

Common situations: Consul/Kubernetes registration missing the port or exposing a metadata port; static address-list entries malformed; service registered with secure=false/true mismatch leading to unusable port; DNS name not resolvable from the container.

Related errors

• No service definition for serviceName ${serviceName} found.
• invalid configuration for a Stork Load Balancer : ${loadBala
• gRPC client '${name}' cannot use both domain-socket and Stor
• Got unexpected HTTP response code ${r.statusCode()} from ${r
• Trying to use a StorkClientRequestFilter but the quarkus-sma

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