alibaba/spring-ai-alibaba · error · RuntimeException

Tool definition name is not available

Error message

Tool definition name is not available

What it means

To invoke a remote MCP tool over SSE/streamable HTTP, the gateway must know the actual MCP tool name. It derives it from toolDefinition.name(), which normally follows the pattern 'serverName_tools_toolName'. If the definition name is null or empty the extraction is impossible, so handleMcpStreamProtocol throws a RuntimeException.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/tools/NacosMcpGatewayToolCallback.java:493

			// 构建基础URL，根据协议类型调整
			String transportProtocol = StringUtils.hasText(serviceRef.getTransportProtocol()) ? serviceRef.getTransportProtocol() : "http";
			StringBuilder baseUrl;
			if ("mcp-sse".equalsIgnoreCase(protocol)) {
				baseUrl = new StringBuilder(transportProtocol + "://" + mcpEndpointInfo.getAddress() + ":" + mcpEndpointInfo.getPort());
			}
			else {
				// mcp-streamable 或其他协议
				baseUrl = new StringBuilder(transportProtocol + "://" + mcpEndpointInfo.getAddress() + ":" + mcpEndpointInfo.getPort());
			}

			logger.info("[handleMcpStreamProtocol] Processing {} protocol with args: {} and baseUrl: {}", protocol,
					args, baseUrl.toString());

			try {
				// 获取工具名称 - 从工具定义名称中提取实际的工具名称
				String toolDefinitionName = this.toolDefinition.name();
				if (toolDefinitionName == null || toolDefinitionName.isEmpty()) {
					throw new RuntimeException("Tool definition name is not available");
				}

				// 工具定义名称格式为: serverName_tools_toolName
				// 需要提取最后的 toolName 部分
				String toolName;
				if (toolDefinitionName.contains("_tools_")) {
					toolName = toolDefinitionName.substring(toolDefinitionName.lastIndexOf("_tools_") + 7);
				}
				else {
					// 如果没有 _tools_ 分隔符，使用整个名称
					toolName = toolDefinitionName;
				}

				if (toolName.isEmpty()) {
					throw new RuntimeException("Extracted tool name is empty");
				}

				// 构建传输层

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure the ToolDefinition passed to NacosMcpGatewayToolCallback is built with a non-empty name following the 'serverName_tools_toolName' convention.
2. Validate tool metadata coming from Nacos before creating callbacks; skip or repair definitions with blank names.
3. If wrapping the callback, delegate name() to the underlying definition instead of returning null.

Example fix

// before
ToolDefinition.builder().description(desc).inputSchema(schema).build(); // no name
// after
ToolDefinition.builder().name(serverName + "_tools_" + toolName).description(desc).inputSchema(schema).build();

String name = toolDefinition.name();
if (name == null || name.isEmpty()) {
    throw new IllegalArgumentException("ToolDefinition must have a non-empty name before gateway registration");
}

if (toolDefinition == null || toolDefinition.name() == null || toolDefinition.name().isBlank()) { /* reject */ }

try { return callback.call(args); }
catch (RuntimeException e) {
    if ("Tool definition name is not available".equals(e.getMessage())) { log.error("misconfigured tool definition"); }
    throw e;
}

When it happens

Trigger: call() -> handleMcpStreamProtocol where this.toolDefinition.name() returns null or "" — e.g. the callback was built with a ToolDefinition lacking a name, or the name was blanked when wrapping/renaming the callback.

Common situations: Programmatic ToolDefinition construction that omitted .name(...); a wrapper/proxy callback that replaced the original definition with an unnamed one; data corruption in tool metadata synced from Nacos.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Tool definition is null
• Protocol is null
• Remote server config is null
• No available endpoint found for service: <serviceName>
• Extracted tool name is empty

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/c253d4392aa587ec. Report an issue: GitHub.