apache/shenyu · error · ShenyuException

illegal param, serverLists configuration required if…

Error message

illegal param, serverLists configuration required if registerType equals local.

What it means

AbstractShenyuSdkClient.loadBalancerInstances, when no registry repository is wired (registerType local), builds upstreams from shenyu.register.serverLists; an empty list means no gateway addresses were configured so load balancing cannot proceed and a ShenyuException is thrown.

Solutions

  1. Set shenyu.register.serverLists with comma-separated gateway addresses in local mode
  2. Verify the SDK register config is loaded (check the config file/profile)
  3. If instances should come from a registry, configure registerType so registerRepository is initialized instead of local mode
  4. Validate the property is non-blank before SDK startup

Example fix

// before
shenyu:
  register:
    registerType: local
# serverLists missing
// after
shenyu:
  register:
    registerType: local
    serverLists: http://127.0.0.1:9195,http://127.0.0.1:9196
Defensive patterns

Strategy: validation

Validate before calling

String sl = registerConfig.getServerLists(); if (registerRepository == null && (sl == null || sl.isBlank())) throw new IllegalStateException("local mode requires shenyu.register.serverLists");

Try / catch

try { client.send(request); } catch (ShenyuException e) { log.error("sdk routing failed: {}", e.getMessage()); }

Prevention

When it happens

Trigger: shenyuRequest -> loadBalancerInstances with registerRepository == null and registerConfig.getServerLists() null/empty (split of null path or blank string yielding empty list).

Common situations: Using the SDK in local mode without configuring serverLists; property name typo; config not loaded from the expected file; migrating from a registered deployment to local mode without adding the address list.

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/05ef7809034b9ee4. Report an issue: GitHub.

Appendix: source

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

        if (Objects.nonNull(requestInterceptors)) {
            requestInterceptors.forEach(interceptor -> interceptor.apply(shenyuRequest));
        }
        return shenyuRequest;
    }

    /**
     * get rewrite url by request.
     *
     * @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();

View on GitHub (pinned to 567142e072)