{"record":{"id":"05ef7809034b9ee4","repo":"apache/shenyu","slug":"illegal-param-serverlists-configuration-required-if","errorCode":null,"errorMessage":"illegal param, serverLists configuration required if registerType equals local.","messagePattern":"illegal param, serverLists configuration required if registerType equals local\\.","errorType":"validation","errorClass":"ShenyuException","httpStatus":null,"severity":"error","filePath":"shenyu-sdk/shenyu-sdk-core/src/main/java/org/apache/shenyu/sdk/core/client/AbstractShenyuSdkClient.java","lineNumber":155,"sourceCode":"        if (Objects.nonNull(requestInterceptors)) {\n            requestInterceptors.forEach(interceptor -> interceptor.apply(shenyuRequest));\n        }\n        return shenyuRequest;\n    }\n\n    /**\n     * get rewrite url by request.\n     *\n     * @param request the request.\n     * @return {@linkplain String}\n     */\n    private String loadBalancerInstances(final ShenyuRequest request) {\n        // all addresses of registry\n        final List<Upstream> upstreams;\n        if (Objects.isNull(registerRepository)) {\n            List<String> serverList = Arrays.asList(registerConfig.getServerLists().split(\",\"));\n            if (serverList.isEmpty()) {\n                throw new ShenyuException(\"illegal param, serverLists configuration required if registerType equals local.\");\n            }\n            upstreams = serverList.stream()\n                    .map(serverAddress -> Upstream.builder().url(UriUtils.appendScheme(serverAddress, scheme)).build())\n                    .collect(Collectors.toList());\n        } else {\n            List<InstanceEntity> instanceRegisters = registerRepository.selectInstances(request.getName());\n            if (ObjectUtils.isEmpty(instanceRegisters)) {\n                throw new ShenyuException(\"Gateway address not found from registry.\");\n            }\n            upstreams = instanceRegisters.stream()\n                    .map(instanceRegister -> {\n                        final String instanceUrl = String.join(Constants.COLONS, instanceRegister.getHost(), Integer.toString(instanceRegister.getPort()));\n                        return Upstream.builder().url(UriUtils.appendScheme(instanceUrl, scheme)).build();\n                    })\n                    .collect(Collectors.toList());\n        }\n        // loadBalancer upstreams\n        LoadBalanceData data = new LoadBalanceData();","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-sdk/shenyu-sdk-core/src/main/java/org/apache/shenyu/sdk/core/client/AbstractShenyuSdkClient.java#L137-L173","documentation":"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.","triggerScenarios":"shenyuRequest -> loadBalancerInstances with registerRepository == null and registerConfig.getServerLists() null/empty (split of null path or blank string yielding empty list).","commonSituations":"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.","solutions":["Set shenyu.register.serverLists with comma-separated gateway addresses in local mode","Verify the SDK register config is loaded (check the config file/profile)","If instances should come from a registry, configure registerType so registerRepository is initialized instead of local mode","Validate the property is non-blank before SDK startup"],"exampleFix":"// before\nshenyu:\n  register:\n    registerType: local\n# serverLists missing\n// after\nshenyu:\n  register:\n    registerType: local\n    serverLists: http://127.0.0.1:9195,http://127.0.0.1:9196","handlingStrategy":"validation","validationCode":"String sl = registerConfig.getServerLists(); if (registerRepository == null && (sl == null || sl.isBlank())) throw new IllegalStateException(\"local mode requires shenyu.register.serverLists\");","typeGuard":null,"tryCatchPattern":"try { client.send(request); } catch (ShenyuException e) { log.error(\"sdk routing failed: {}\", e.getMessage()); }","preventionTips":["Configure serverLists whenever registerType is local","Document required SDK properties per deployment mode","Validate config at SDK builder time"],"tags":["sdk","config","loadbalancer"],"backgroundTag":"missing-required-config-field","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}