apache/shenyu · error · ShenyuException

illegal param, serverLists configuration required if…

Error message

illegal param, serverLists configuration required if registerType equals local.

What it means

ShenyuDiscoveryClient.getInstance() supports two discovery modes. When no register repository is wired (local/static mode), it builds the instance list from registerConfig.getServerLists(); a null serverLists makes split() throw NPE, and a list that ends up empty is rejected with this ShenyuException. The SDK needs at least one gateway address to route SDK calls.

Solutions

Set the server lists in configuration, e.g. shenyu.register.serverLists: http://gw1:9195,http://gw2:9195 (comma-separated).
Verify the config actually reaches ShenyuRegisterConfig (correct prefix, profile active, env var present).
If you intend registry-based discovery, configure the registerType and repository so registerRepository is non-null instead of relying on serverLists.

Example fix

// before (application.yml)
shenyu:
  register:
    registerType: local
// after
shenyu:
  register:
    registerType: local
    serverLists: http://localhost:9195

Defensive patterns

Strategy: validation

Validate before calling

String serverLists = registerConfig.getServerLists();
if (registerRepository == null && (serverLists == null || serverLists.isBlank())) {
    throw new IllegalStateException("shenyu register.serverLists is required when no register repository is configured");
}

Prevention

Set serverLists whenever registerType is local or the repository is absent.
Validate SDK config at application startup, before the first SDK call.
Keep registry-based and static-based config examples separate to avoid mixing them.

When it happens

Trigger: Running the feign SDK with registerType local (or with registerRepository unset) while shenyu.sdk serverLists is absent or empty, then calling getInstance/serviceInstance for any serviceId.

Common situations: Missing serverLists key in application.yml; property name typo; copying config from a registry-based setup (zookeeper/nacos) that never sets serverLists; env var not injected in the deployment.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

    public ShenyuDiscoveryClient(final ShenyuInstanceRegisterRepository registerRepository, final RegisterConfig registerConfig) {
        this.registerRepository = registerRepository;
        this.registerConfig = registerConfig;
        Properties props = registerConfig.getProps();
        this.algorithm = props.getProperty("algorithm", "roundRobin");
        this.scheme = props.getProperty("scheme", HttpSchemeEnum.HTTP.getScheme());
    }

    /**
     * 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) {

View on GitHub (pinned to 567142e072)