apache/shenyu · error · ShenyuException

please config in xml/yml !

Error message

please config ${shenyu.client.http.props.port} in xml/yml !

What it means

SpringWebSocketClientEventListener.buildURIRegisterDTO() computes the websocket URI from the configured port; if reading the port throws ShenyuException (blank/missing shenyu.client.websocket.props.port), the catch rethrows a ShenyuException appending a hint to configure that property in xml/yml. The message preserves the original cause text from getPort().

Solutions

Add shenyu.client.websocket.props.port (the backend websocket service port, e.g. 8888) to application.yml or xml props.
Ensure the port value is numeric and readable — check the original message text prepended to the hint for the real cause.
Confirm the config is under shenyu.client.websocket (this listener extends the http client config but the hint text says http.props.port historically).
Restart after fixing; the check occurs when URI register DTOs are built at startup.

Example fix

// before
shenyu:
  client:
    websocket:
      props:
        contextPath: /websocket
// after
shenyu:
  client:
    websocket:
      props:
        contextPath: /websocket
        port: 8888

Defensive patterns

Strategy: validation

Validate before calling

String port = props.getProperty("port");
if (port == null || !port.matches("\\d+")) {
    throw new IllegalStateException("shenyu.client.websocket.props.port must be a number");
}

Try / catch

try {
    URI dto = buildURIRegisterDTO(bean);
} catch (ShenyuException e) {
    LOG.error("Websocket client config invalid: {}", e.getMessage());
}

Prevention

Include port in the websocket client props block of every environment's config.
Use config validation (spring boot configuration metadata / @Validated) for shenyu.client.* props.
Read the full message: the original cause text is prepended before the config hint.

When it happens

Trigger: buildURIRegisterDTO() is invoked (via getBeans during client startup) while the props map for the websocket client has no 'port' entry or it is not a parseable integer, causing getPort()/Integer.valueOf to fail.

Common situations: application.yml missing shenyu.client.websocket.props.port; port set to a non-numeric string; config block named incorrectly (e.g. http instead of websocket) so defaults resolve to blank.

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/3ccdf4e0f98175be. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-client/shenyu-client-websocket/shenyu-client-spring-websocket/src/main/java/org/apache/shenyu/client/spring/websocket/init/SpringWebSocketClientEventListener.java:134

    }

    @Override
    protected URIRegisterDTO buildURIRegisterDTO(final ApplicationContext context,
                                                 final Map<String, Object> beans,
                                                 final String namespaceId) {
        try {
            return URIRegisterDTO.builder()
                    .contextPath(getContextPath())
                    .appName(getAppName())
                    .protocol(protocol)
                    .host(super.getHost())
                    .port(Integer.valueOf(getPort()))
                    .rpcType(RpcTypeEnum.WEB_SOCKET.getName())
                    .eventType(EventType.REGISTER)
                    .namespaceId(namespaceId)
                    .build();
        } catch (ShenyuException e) {
            throw new ShenyuException(e.getMessage() + "please config ${shenyu.client.http.props.port} in xml/yml !");
        }
    }
    
    @Override
    protected String getClientName() {
        return RpcTypeEnum.WEB_SOCKET.getName();
    }
    
    @Override
    protected void handle(final String beanName, final Object bean) {
        Class<?> clazz = getCorrectedClass(bean);
        final ShenyuSpringWebSocketClient beanShenyuClient = AnnotatedElementUtils.findMergedAnnotation(clazz, getAnnotationType());
        final String superPath = buildApiSuperPath(clazz, beanShenyuClient);
        // Compatible with previous versions
        if (Objects.nonNull(beanShenyuClient)) {
            handleClass(clazz, bean, beanShenyuClient, superPath);
            return;
        }

View on GitHub (pinned to 567142e072)