alibaba/spring-ai-alibaba · error · IllegalStateException

Remote server config is null

Error message

Remote server config is null

What it means

NacosMcpGatewayToolCallback.call() routes MCP tool invocations by protocol. When the protocol resolves to 'mcp-sse', the callback requires the tool definition to carry a McpServerRemoteServiceConfig (service ref, export path, etc.). If that nested config object is absent, the gateway has no remote server to route the call to, so it throws this IllegalStateException instead of failing later with a confusing NPE.

Source

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

					args = objectMapper.readValue(input, Map.class);
					logger.info("[call] parsed args: {}", args);
				}
				catch (Exception e) {
					logger.error("[call] Failed to parse input to args", e);
					// 如果解析失败，尝试作为单个参数处理
					args.put("input", input);
				}
			}

			String protocol = this.toolDefinition.getProtocol();
			if (protocol == null) {
				throw new IllegalStateException("Protocol is null");
			}

			if ("mcp-sse".equalsIgnoreCase(protocol)) {
				McpServerRemoteServiceConfig remoteServerConfig = this.toolDefinition.getRemoteServerConfig();
				if (remoteServerConfig == null) {
					throw new IllegalStateException("Remote server config is null");
				}
				return handleMcpStreamProtocol(args, remoteServerConfig, protocol);
			}
			else if ("mcp-streamable".equalsIgnoreCase(protocol)) {

				logger.error("[call] Unsupported protocol: {}", protocol);
				return "Error: Unsupported protocol " + protocol;
				// McpServerRemoteServiceConfig remoteServerConfig =
				// this.toolDefinition.getRemoteServerConfig();
				// if (remoteServerConfig == null) {
				// throw new IllegalStateException("Remote server config is null");
				// }
				// return handleMcpStreamableProtocol(args, remoteServerConfig, protocol);
			}
			else {
				logger.error("[call] Unsupported protocol: {}", protocol);
				return "Error: Unsupported protocol " + protocol;
			}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Verify the MCP service metadata in Nacos includes the remote server config (serviceRef/exportPath) and re-publish the service so the tool definition is regenerated with it.
2. Check the code path that builds the ToolDefinition for the gateway and ensure setRemoteServerConfig / the builder field is populated before registering the callback.
3. If the tool is genuinely not remote-capable, filter it out before call() instead of invoking it.

Example fix

// before
ToolDefinition def = ToolDefinition.builder().name(name).description(desc).inputSchema(schema).build();
// after
ToolDefinition def = ToolDefinition.builder().name(name).description(desc).inputSchema(schema)
    .remoteServerConfig(mcpServerRemoteServiceConfig) // must be set for mcp-sse protocol
    .build();

if (callback.getToolDefinition().getRemoteServerConfig() == null) {
    throw new IllegalArgumentException("Tool definition missing remoteServerConfig for MCP gateway call");
}

McpServerRemoteServiceConfig cfg = toolDefinition.getRemoteServerConfig();
if (cfg == null || cfg.getServiceRef() == null) { /* skip or repair this tool */ }

try { return callback.call(args); }
catch (IllegalStateException e) {
    if (e.getMessage().contains("Remote server config is null")) { log.warn("skip tool: no remote config"); return fallback; }
    throw e;
}

When it happens

Trigger: Calling ToolCallback.call() on a gateway callback whose ToolDefinition was built without remoteServerConfig while toolDefinition.protocol() equals 'mcp-sse' (case-insensitive).

Common situations: A Nacos-registered MCP service was converted into a tool definition without its remote server config block (missing mcpServerRemoteServiceConfig in the MCP server metadata pulled from Nacos), or tool definitions were hand-constructed/copied and the remoteServerConfig field was dropped.

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

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

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