apache/shenyu · error · ShenyuException

Gateway address not found from registry.

Error message

Gateway address not found from registry.

What it means

In the registered (non-local) mode, loadBalancerInstances asks the register repository for instances of the request's service name; when selectInstances returns nothing the SDK cannot route the request and throws a ShenyuException.

Solutions

1. Verify request.getName() matches the service name under which gateway instances registered
2. Check the registry (e.g. Consul UI) for live instances of that service
3. Confirm SDK registry connection settings (serverLists, namespace) point at the registry the gateways use
4. Start at least one healthy gateway instance and wait for registration before issuing SDK requests

List<InstanceEntity> instances = registerRepository.selectInstances(name); if (instances == null || instances.isEmpty()) { useFallbackAddress(); }

try { sdkClient.send(request); } catch (ShenyuException e) { log.warn("no instances for {} in registry; retrying/failing over", request.getName()); retryWithBackoff(); }

When it happens

Trigger: shenyuRequest -> loadBalancerInstances where registerRepository.selectInstances(request.getName()) returns null or an empty list — the service has no registered/healthy instances.

Common situations: Gateway service name mismatch between SDK request and registered instances; all gateway instances down or deregistered; registry (consul/zookeeper/etc.) not synced or client connected to the wrong registry namespace; SDK called before the first gateway instance registered.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• illegal param, serverLists configuration required if…
• shenyu TcpProxy don't have any upstream
• Gateway address not found from registry.
• Invalid upstream URL, expected 'host:port' format but was:
• please config the registerType and serverList

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/1d9a2eaf7d80a8e3. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-sdk/shenyu-sdk-core/src/main/java/org/apache/shenyu/sdk/core/client/AbstractShenyuSdkClient.java:163

     *
     * @param request the request.
     * @return {@linkplain String}
     */
    private String loadBalancerInstances(final ShenyuRequest request) {
        // all addresses of registry
        final List<Upstream> upstreams;
        if (Objects.isNull(registerRepository)) {
            List<String> serverList = Arrays.asList(registerConfig.getServerLists().split(","));
            if (serverList.isEmpty()) {
                throw new ShenyuException("illegal param, serverLists configuration required if registerType equals local.");
            }
            upstreams = serverList.stream()
                    .map(serverAddress -> Upstream.builder().url(UriUtils.appendScheme(serverAddress, scheme)).build())
                    .collect(Collectors.toList());
        } else {
            List<InstanceEntity> instanceRegisters = registerRepository.selectInstances(request.getName());
            if (ObjectUtils.isEmpty(instanceRegisters)) {
                throw new ShenyuException("Gateway address not found from registry.");
            }
            upstreams = instanceRegisters.stream()
                    .map(instanceRegister -> {
                        final String instanceUrl = String.join(Constants.COLONS, instanceRegister.getHost(), Integer.toString(instanceRegister.getPort()));
                        return Upstream.builder().url(UriUtils.appendScheme(instanceUrl, scheme)).build();
                    })
                    .collect(Collectors.toList());
        }
        // loadBalancer upstreams
        LoadBalanceData data = new LoadBalanceData();
        data.setHeaders(request.getHeaders());
        data.setHttpMethod(request.getHttpMethod().name());
        final Upstream upstream = LoadBalancerFactory.selector(upstreams, algorithm, data);
        return replaceUrl(upstream.getUrl(), request.getUrl());
    }

    private String replaceUrl(final String url, final String sourceUrl) {
        final URI uri = URI.create(sourceUrl);

View on GitHub (pinned to 567142e072)