alibaba/spring-ai-alibaba · error · IllegalStateException

Protocol is null

Error message

Protocol is null

What it means

Thrown by NacosMcpGatewayToolCallback.call when the toolDefinition's protocol field is null. The protocol (e.g. 'mcp-sse', 'http') selects the transport used to invoke the remote tool, so call aborts with IllegalStateException when it is missing.

Source

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

			// input解析
			logger.info("[call] input string: {}", input);
			Map<String, Object> args = new HashMap<>();
			if (!input.isEmpty()) {
				try {
					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");
				// }

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set the protocol attribute (e.g. 'mcp-sse' or 'http') in the Nacos MCP service metadata and reload.
2. Verify the metadata key name matches what the deserializer expects (case/spelling).
3. Re-register or upgrade stale Nacos service entries that predate the protocol field.
4. Add a startup-time validation of tool definitions so missing protocols fail before first call.

Example fix

// before (Nacos metadata JSON)
{"name": "weather-tool", "remoteServerConfig": {...}}
// after
{"name": "weather-tool", "protocol": "mcp-sse", "remoteServerConfig": {...}}

boolean hasProtocol(ToolDefinition td) {
    return td != null && td.getProtocol() != null && !td.getProtocol().isBlank();
}
// check before invoking the tool
// if (!hasProtocol(toolDefinition)) throw new IllegalStateException("Protocol metadata missing in Nacos service descriptor");

try {
    return callback.call(input);
} catch (IllegalStateException e) {
    if ("Protocol is null".equals(e.getMessage())) {
        logger.error("Tool '{}' from Nacos lacks protocol metadata; re-register the service", toolName);
    }
    throw e;
}

When it happens

Trigger: A ToolDefinition loaded from Nacos whose protocol attribute is absent or null reaches call(); the check occurs right after the null-definition check and before protocol-based dispatch (mcp-sse vs other transports).

Common situations: Nacos MCP service registered without the protocol metadata field; typo in the metadata key so the protocol never binds; older Nacos registry entries from before the protocol field was introduced.

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
• Remote server config 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/5e0420a90ad5210a. Report an issue: GitHub.