apache/shenyu · error · ShenyuClientIllegalArgumentException

tars client must config the contextPath, ipAndPort

Error message

tars client must config the contextPath, ipAndPort

What it means

TarsServiceBeanEventListener validates at startup that the Tars client has a non-blank contextPath, host, and port configured under shenyu.client.tars.props. If any of these is missing or empty, the client cannot build the registration metadata (rpcType/contextPath/ipAndPort) needed to register the Tars service with shenyu-admin, so construction fails fast with ShenyuClientIllegalArgumentException.

Solutions

Add shenyu.client.tars.props.contextPath (e.g. /tars) and shenyu.client.tars.props.port (e.g. 8123) to application.yml or the XML properties for the client.
Verify the register section (serverLists, and host/thrift ip settings) is present so this.getHost() resolves to a non-blank value.
Confirm the properties are under the correct client name key matching getClientName() (tars), not under another rpcType block.
Restart the application after editing config; this check runs only during bean-listener construction.

Example fix

// before (application.yml)
shenyu:
  client:
    tars:
      props: {}
// after
shenyu:
  client:
    tars:
      register:
        serverLists: http://localhost:9095
      props:
        contextPath: /tars
        port: 8123

Defensive patterns

Strategy: validation

Validate before calling

Properties props = clientConfig.getClient().get("tars").getProps();
if (StringUtils.isAnyBlank(props.getProperty("contextPath"), props.getProperty("port"))) {
    throw new IllegalStateException("tars client requires props.contextPath and props.port");
}

Try / catch

try {
    new TarsServiceBeanEventListener(clientConfig, repo);
} catch (ShenyuClientIllegalArgumentException e) {
    LOG.error("Tars client misconfigured: {}", e.getMessage());
}

Prevention

Keep a shared application.yml template including contextPath and port for every rpcType client.
Add a startup config validator test that asserts required props exist per rpcType.

When it happens

Trigger: Constructing TarsServiceBeanEventListener when the Properties from clientConfig.getClient().get(clientName).getProps() lack 'contextPath' or 'port', or when the resolved host is blank (e.g. shenyu.client.tars.register.* host settings absent).

Common situations: Spring Boot application.yml missing shenyu.client.tars.props.context-path or props.port keys; copying a config from another rpcType sample that used different prop names; running in a container where the host cannot be auto-detected and none was configured.

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/5892d9b1f1a9b56a. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-client/shenyu-client-tars/src/main/java/org/apache/shenyu/client/tars/TarsServiceBeanEventListener.java:76

 * The Tars ServiceBean EventListener.
 */
public class TarsServiceBeanEventListener extends AbstractContextRefreshedEventListener<Object, ShenyuTarsClient> {

    private final StandardReflectionParameterNameDiscoverer localVariableTableParameterNameDiscoverer = new StandardReflectionParameterNameDiscoverer();

    private final ShenyuClientRegisterEventPublisher publisher = ShenyuClientRegisterEventPublisher.getInstance();

    private final String contextPath;

    private final String ipAndPort;

    public TarsServiceBeanEventListener(final ShenyuClientConfig clientConfig, final ShenyuClientRegisterRepository shenyuClientRegisterRepository) {
        super(clientConfig, shenyuClientRegisterRepository);
        Properties props = clientConfig.getClient().get(getClientName()).getProps();
        String contextPath = props.getProperty(ShenyuClientConstants.CONTEXT_PATH);
        String port = props.getProperty(ShenyuClientConstants.PORT);
        if (StringUtils.isAnyBlank(contextPath, this.getHost(), port)) {
            throw new ShenyuClientIllegalArgumentException("tars client must config the contextPath, ipAndPort");
        }
        this.contextPath = contextPath;
        this.ipAndPort = this.getHost() + ":" + port;
        publisher.start(shenyuClientRegisterRepository);
    }

    @Override
    protected Sextet<String[], String, String, ApiHttpMethodEnum[], RpcTypeEnum, String> buildApiDocSextet(final Method method, final Annotation annotation, final Map<String, Object> beans) {
        ShenyuTarsClient shenyuTarsClient = AnnotatedElementUtils.findMergedAnnotation(method, ShenyuTarsClient.class);
        if (Objects.isNull(shenyuTarsClient)) {
            return null;
        }
        String produce = ShenyuClientConstants.MEDIA_TYPE_ALL_VALUE;
        String consume = ShenyuClientConstants.MEDIA_TYPE_ALL_VALUE;
        String[] values = new String[]{shenyuTarsClient.value()};
        ApiHttpMethodEnum[] apiHttpMethodEnums = new ApiHttpMethodEnum[]{ApiHttpMethodEnum.NOT_HTTP};
        String version = "v0.01";
        return Sextet.with(values, consume, produce, apiHttpMethodEnums, RpcTypeEnum.TARS, version);

View on GitHub (pinned to 567142e072)