What causes "OpenAPI pathKey cannot be null or empty" in apache/shenyu?

Set pathKey on the OpenApiConfig for each @ShenyuMcpTool

apache/shenyu · error · IllegalArgumentException

OpenAPI pathKey cannot be null or empty

Error message

OpenAPI pathKey cannot be null or empty

What it means

McpServiceEventListener.validateClientConfig checks each MCP tool registration: the OpenAPI url (pathKey) must be non-blank. If blank, it logs that OpenApiConfig is misconfigured and throws IllegalArgumentException, aborting the tool's registration DTO build.

Solutions

Set pathKey on the OpenApiConfig for each @ShenyuMcpTool
Verify the tool definition's url field is populated before registration
Check logs for 'OpenAPI pathKey is null or empty' to locate the offending tool
Regenerate tool configs from the OpenAPI spec ensuring path fields are present

Example fix

// before
@ShenyuMcpTool(name = "weather")
// after
@ShenyuMcpTool(name = "weather", openApiConfig = @OpenApiConfig(pathKey = "/weather", methodType = "GET"))

Defensive patterns

Strategy: validation

Validate before calling

if (tool.getOpenApiConfig() == null || StringUtils.isBlank(tool.getOpenApiConfig().getPathKey())) {
    throw new IllegalStateException("@ShenyuMcpTool " + tool.getName() + " missing OpenApiConfig pathKey");
}

Try / catch

try { listener.buildMcpToolsRegisterDTO(tool); }
catch (IllegalArgumentException e) {
    log.error("MCP tool config invalid: {}", e.getMessage());
}

Prevention

Annotate every @ShenyuMcpTool with a complete OpenApiConfig
Run an annotation scan at startup to verify pathKey presence
Regenerate tool configs from the OpenAPI spec

When it happens

Trigger: Building MCP tools register DTOs when the ShenyuMcpTool's associated OpenAPI url/pathKey is null or empty — i.e. the OpenApiConfig did not supply a pathKey for the tool.

Common situations: OpenApiConfig annotation/property omitted; pathKey property misspelled; tool definitions generated from OpenAPI specs missing the path mapping.

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

Appendix: source

Thrown at shenyu-client/shenyu-client-mcp/shenyu-client-mcp-register/src/main/java/org/apache/shenyu/client/mcp/McpServiceEventListener.java:378

    private McpToolsRegisterDTO buildMcpToolsRegisterDTO(final Object bean, final Class<?> clazz,
                                                         final ShenyuMcpTool classShenyuClient,
                                                         final org.apache.shenyu.client.mcp.common.dto.ShenyuMcpTool shenyuMcpTool,
                                                         final String superPath, final Method method,
                                                         final String url, final String namespaceId) {
        validateClientConfig(shenyuMcpTool, url);
        JsonObject openApiJson = McpOpenApiGenerator.generateOpenApiJson(classShenyuClient, shenyuMcpTool, url);
        McpToolsRegisterDTO mcpToolsRegisterDTO = McpToolsRegisterDTOGenerator.generateRegisterDTO(shenyuMcpTool, openApiJson, url, namespaceId);
        MetaDataRegisterDTO metaDataRegisterDTO = buildMetaDataDTO(bean, classShenyuClient, url, clazz, method, namespaceId);
        metaDataRegisterDTO.setEnabled(shenyuMcpTool.getEnable());
        mcpToolsRegisterDTO.setMetaDataRegisterDTO(metaDataRegisterDTO);
        return mcpToolsRegisterDTO;
    }

    private void validateClientConfig(final org.apache.shenyu.client.mcp.common.dto.ShenyuMcpTool methodShenyuClient, final String url) {
        if (StringUtils.isBlank(url)) {
            log.error("OpenAPI pathKey is null or empty, please check OpenApiConfig");
            throw new IllegalArgumentException("OpenAPI pathKey cannot be null or empty");
        }

        if (StringUtils.isBlank(methodShenyuClient.getMethod())) {
            log.error("OpenAPI methodType is null or empty, please check OpenApiConfig");
            throw new IllegalArgumentException("OpenAPI methodType cannot be null or empty");
        }
    }

}

View on GitHub (pinned to 567142e072)