apache/shenyu · critical · ShenyuClientIllegalArgumentException

grpc client must config the contextPath, ipAndPort

Error message

grpc client must config the contextPath, ipAndPort

What it means

GrpcClientEventListener's constructor validates that the ShenYu gRPC client configuration provides contextPath, ipAndPort, and port. If any of these is blank, the listener cannot build API registrations, so it throws ShenyuClientIllegalArgumentException at bean construction time, failing application startup.

Solutions

1. Add contextPath, ipAndPort, and port under shenyu.client.grpc.props in application.yml
2. Verify the config is bound: check ShenyuClientConfig props map keys match exactly
3. Check yaml indentation so values are not parsed as null
4. Start from the official shenyu-examples grpc config as a template

Example fix

// before
shenyu:
  client:
    grpc:
      props: {}
// after
shenyu:
  client:
    grpc:
      props:
        contextPath: /grpc
        ipAndPort: 127.0.0.1:8080
        port: 8080

Map<String, String> props = clientConfig.getGrpc().getProps();
if (props == null || props.values().stream().anyMatch(StringUtils::isBlank)
        || !props.keySet().containsAll(List.of("contextPath", "ipAndPort", "port"))) {
    throw new IllegalStateException("shenyu.client.grpc props must set contextPath, ipAndPort, port");
}

try { new GrpcClientEventListener(clientConfig, repository); }
catch (ShenyuClientIllegalArgumentException e) {
    throw new IllegalStateException("Fix shenyu.client.grpc config: " + e.getMessage());
}

When it happens

Trigger: Constructing/starting the gRPC client (Spring bean creation) when shenyu.client.grpc props lack contextPath, ipAndPort, or port — e.g. empty or missing keys in application.yml.

Common situations: Copy-pasting config from another client type (http, dubbo) that uses different prop names; forgetting the props block entirely; yaml indentation errors making values null.

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

• shenyu.jwt.secretKey is not configured. In a multi-instance…
• clientConfig must config " + getClientName() + " properties
• zookeeper url is empty
• shared thread pool is not enable, config
• is malformed

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

Appendix: source

Thrown at shenyu-client/shenyu-client-grpc/src/main/java/org/apache/shenyu/client/grpc/GrpcClientEventListener.java:72

import java.util.stream.Collectors;

/**
 * The type Shenyu grpc client event listener.
 */
public class GrpcClientEventListener extends AbstractContextRefreshedEventListener<BindableService, ShenyuGrpcClient> {
    
    private final List<ServerServiceDefinition> serviceDefinitions = Lists.newArrayList();
    
    /**
     * Instantiates a new Shenyu client bean post processor.
     *
     * @param clientConfig the shenyu grpc client config
     * @param shenyuClientRegisterRepository the shenyuClientRegisterRepository
     */
    public GrpcClientEventListener(final ShenyuClientConfig clientConfig, final ShenyuClientRegisterRepository shenyuClientRegisterRepository) {
        super(clientConfig, shenyuClientRegisterRepository);
        if (StringUtils.isAnyBlank(getContextPath(), getIpAndPort(), getPort())) {
            throw new ShenyuClientIllegalArgumentException("grpc client must config the contextPath, ipAndPort");
        }
    }

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

    @Override

View on GitHub (pinned to 567142e072)