apache/shenyu · error · ShenyuException

Gateway address uri is not invalid.

Error message

Gateway address uri is not invalid.

What it means

After selecting an upstream (load-balanced or single), getInstance() converts the upstream URL into a java.net.URI via UriUtils.createUri(). If that returns null the URL was unparseable, so the SDK throws ShenyuException rather than returning a ServiceInstance with null host/port.

Solutions

1. Fix the offending upstream address in serverLists or in the registry so it parses as host:port, e.g. http://localhost:9195.
2. Ensure the configured scheme is valid (http/https) so UriUtils.appendScheme produces a well-formed URL.
3. Trim whitespace and stray commas from the comma-separated server list.
4. Log/inspect upstream.getUrl() just before the call to identify which entry is malformed.

Example fix

// before
serverLists: " http://localhost:9195, "
// after
serverLists: "http://localhost:9195"

for (String addr : serverLists.split(",")) {
    String trimmed = addr.trim();
    if (!trimmed.isEmpty() && UriUtils.createUri(UriUtils.appendScheme(trimmed, "http")) == null) {
        throw new IllegalArgumentException("Unparseable gateway address: " + trimmed);
    }
}

When it happens

Trigger: An upstream URL from serverLists or the registry that UriUtils.createUri cannot parse — e.g. missing scheme after appendScheme fails, empty string, or characters illegal in a URI.

Common situations: serverLists entries without a valid scheme and a bad scheme configuration; registry storing malformed host values; whitespace or commas left in the configured address list; configuring an IPv6 literal without brackets.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• shenyu discovery mode current didn't support
• The configuration shenyu.discovery.serverList in xml/yml…
• illegal param, serverLists configuration required if…
• shenyu.jwt.secretKey is not configured. In a multi-instance…
• before start ProxySelector you need init DiscoveryId=

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

Appendix: source

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

                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.");
        }
        return new DefaultServiceInstance(upstream.getUrl(), serviceId, uri.getHost(), uri.getPort(), HttpSchemeEnum.HTTPS.getScheme().equals(scheme));
    }

}

View on GitHub (pinned to 567142e072)