apache/shenyu · error · ShenyuClientIllegalArgumentException

clientConfig must config " + getClientName() + " properties

Error message

clientConfig must config " + getClientName() + " properties

What it means

AbstractContextRefreshedEventListener's constructor requires a ClientPropertiesConfig entry for the current client type (e.g. spring-cloud, dubbo) under shenyu.<clientName>. If clientConfig.getClient().get(getClientName()) returns null it throws ShenyuClientIllegalArgumentException. Your backend service has not configured the mandatory client properties for this Shenyu client module.

Solutions

1. Add the required shenyu.<clientName> config block (register.address, register.port, props like contextPath/appName) to application.yml
2. Check YAML indentation — the properties must sit under the exact key getClientName() returns (e.g. shenyu.spring-cloud)
3. Remove the unused shenyu client starter dependency if the service doesn't use that client type
4. After upgrading ShenYu, diff your client config against the current docs/example configs

Example fix

// before (application.yml — missing client block)
shenyu:
  register:
    address: http://localhost:9095
// after
shenyu:
  register:
    address: http://localhost:9095
  client:
    spring-cloud:
      props:
        contextPath: /springcloud
        appName: springcloud
        port: 8081

// before starting the app, ensure the client config exists
ShenyuClientConfig cfg = /* bound shenyu.* properties */;
if (cfg.getClient() == null || !cfg.getClient().containsKey("spring-cloud")) {
    throw new IllegalStateException("add shenyu.client.spring-cloud config to application.yml");
}

try {
    new SpringApplication(App.class).run(args);
} catch (ShenyuClientIllegalArgumentException e) {
    log.error("Shenyu client config missing: {}", e.getMessage());
    // fix yml and restart
}

When it happens

Trigger: Starting a Shenyu client application (Spring MVC/Dubbo/etc. registered via the client starter) without a shenyu.<clientName> properties block (register address/port, contextPath etc.) in application.yml.

Common situations: Copy-pasting a bootstrap config from a service using a different client type; upgrading ShenYu where config keys were renamed/nested; leaving the client starter on the classpath after removing its config; YAML indentation placing properties under the wrong key.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• shenyu.jwt.secretKey is not configured. In a multi-instance…
• client register param must config the appName or contextPath
• The configuration shenyu.discovery.serverList in xml/yml…
• grpc client must config the contextPath, ipAndPort
• zookeeper url is empty

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

Appendix: source

Thrown at shenyu-client/shenyu-client-core/src/main/java/org/apache/shenyu/client/core/client/AbstractContextRefreshedEventListener.java:120

    private ApplicationContext context;

    /**
     * multiple namespace support.
     */
    private final List<String> namespace;

    /**
     * Instantiates a new context refreshed event listener.
     *
     * @param clientConfig                   the shenyu client config
     * @param shenyuClientRegisterRepository the shenyuClientRegisterRepository
     */
    public AbstractContextRefreshedEventListener(final ShenyuClientConfig clientConfig,
                                                 final ShenyuClientRegisterRepository shenyuClientRegisterRepository) {
        ClientPropertiesConfig config = clientConfig.getClient().get(getClientName());
        if (Objects.isNull(config)) {
            throw new ShenyuClientIllegalArgumentException("clientConfig must config " + getClientName() + " properties");
        }
        Properties props = config.getProps();
        String namespace = clientConfig.getNamespace();
        if (StringUtils.isBlank(namespace)) {
            LOG.warn("current shenyu.namespace is null, use default namespace: {}", Constants.SYS_DEFAULT_NAMESPACE_ID);
            namespace = Constants.SYS_DEFAULT_NAMESPACE_ID;
        }
        this.namespace = Lists.newArrayList(StringUtils.split(namespace, Constants.SEPARATOR_CHARS));
        this.appName = props.getProperty(ShenyuClientConstants.APP_NAME);
        this.contextPath = Optional.ofNullable(props.getProperty(ShenyuClientConstants.CONTEXT_PATH)).map(UriUtils::repairData).orElse("");
        if (StringUtils.isBlank(appName) && StringUtils.isBlank(contextPath)) {
            String errorMsg = "client register param must config the appName or contextPath";
            LOG.error(errorMsg);
            throw new ShenyuClientIllegalArgumentException(errorMsg);
        }
        this.ipAndPort = props.getProperty(ShenyuClientConstants.IP_PORT);
        this.host = props.getProperty(ShenyuClientConstants.HOST);
        this.port = props.getProperty(ShenyuClientConstants.PORT);

View on GitHub (pinned to 567142e072)