apache/shenyu · error · ShenyuException

Gateway address not found from registry.

Error message

Gateway address not found from registry.

What it means

In registry mode (registerRepository is set), getInstance() looks up live gateway instances via registerRepository.selectInstances(serviceId). When the registry returns no instances the SDK cannot route the call and throws ShenyuException. This is a runtime discovery failure, unlike the static-mode config error.

Solutions

1. Confirm the gateway is running and registered: inspect the registry directly (e.g. zkCli ls /shenyu/instances) for the serviceId.
2. Check the serviceId string matches exactly what the gateway registers (case, prefix).
3. Verify SDK↔registry connectivity and credentials; fix connection errors so selectInstances returns data.
4. Add retry/fallback with backoff around instance lookup since registration can lag startup.

try {
    ServiceInstance inst = discoveryClient.getInstance(serviceId);
} catch (ShenyuException e) {
    // registry returned no instances: retry with backoff or fall back to a static address
    retry(() -> discoveryClient.getInstance(serviceId), 3, Duration.ofSeconds(2));
}

When it happens

Trigger: Calling getInstance(serviceId) where the registry (zookeeper/nacos/etcd/...) has no registered instances for that serviceId — wrong serviceId, gateway not yet registered, or gateway process down.

Common situations: Typo in the serviceId; gateway started after the SDK call; registry cluster unreachable so the repository cache is empty; instances deregistered after a session expiry; namespace/cluster mismatch between gateway and SDK.

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

• shenyu register into ShenyuDiscoveryService
• registry_id is already exist
• registry is not exist
• Import mcp server config failed:
• Failed to get Swagger document, HTTP status code:

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

Appendix: source

Thrown at shenyu-sdk/shenyu-sdk-feign/src/main/java/org/apache/shenyu/sdk/feign/ShenyuDiscoveryClient.java:84

    }

    /**
     * Gets all ServiceInstances associated with a particular serviceId.
     * @param serviceId The serviceId to query.
     * @return A List of ServiceInstance.
     */
    public ServiceInstance getInstance(final String serviceId) {
        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(serviceId);
            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
        if (CollectionUtils.isEmpty(upstreams)) {
            LOG.error("The serviceId that named {} could not load balanced to at least one upstream.", serviceId);
        }
        Upstream upstream = upstreams.get(0);
        if (CollectionUtils.isNotEmpty(upstreams) && upstreams.size() > 1) {
            upstream = LoadBalancerFactory.selector(upstreams, algorithm, new LoadBalanceData());
        }

        final URI uri = UriUtils.createUri(upstream.getUrl());
        if (Objects.isNull(uri)) {
            throw new ShenyuException("Gateway address uri is not invalid.");

View on GitHub (pinned to 567142e072)