spring-projects/spring-ai · error · IllegalArgumentException

Prefix or toolName cannot be null or empty

Error message

Prefix or toolName cannot be null or empty

What it means

McpToolUtils.prefixedToolName() builds a namespaced MCP tool name from an optional title plus a mandatory connection prefix and the original tool name. It fails fast with IllegalArgumentException when the prefix or the toolName is null/empty, because a missing prefix would defeat collision avoidance and an empty tool name cannot be addressed.

Source

Thrown at mcp/common/src/main/java/org/springframework/ai/mcp/McpToolUtils.java:95

	/**
	 * The name of tool context key used to store the MCP exchange object.
	 */
	public static final String TOOL_CONTEXT_MCP_EXCHANGE_KEY = "exchange";

	private McpToolUtils() {
	}

	/**
	 * @param prefix Client name, combination of client info name and the 'server'
	 * connection name.
	 * @param title Server connection name
	 * @param toolName original MCP server tool name.
	 * @return the prefix to use for the tool to avoid name collisions.
	 */
	public static String prefixedToolName(String prefix, @Nullable String title, String toolName) {

		if (StringUtils.isEmpty(prefix) || StringUtils.isEmpty(toolName)) {
			throw new IllegalArgumentException("Prefix or toolName cannot be null or empty");
		}

		String input = shorten(format(prefix));
		if (!StringUtils.isEmpty(title)) {
			input = input + "_" + format(title); // Do not shorten the title.
		}

		input = input + "_" + format(toolName);

		// If the string is longer than 64 characters, keep the last 64 characters
		if (input.length() > 64) {
			input = input.substring(input.length() - 64);
		}

		return input;
	}

	public static String prefixedToolName(String prefix, String toolName) {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Provide a non-empty connection name prefix for each MCP client (e.g. connectionNamePrefix("weather"))
2. Check spring.ai.mcp.client.connections.<name> properties — the connection key that becomes the prefix must not be empty
3. Verify the MCP server is not advertising tools with empty names (fix or replace the server)
4. If calling the utility manually, guard prefix/toolName with StringUtils.hasText before invoking

Example fix

// before
String name = McpToolUtils.prefixedToolName(null, null, "get_forecast");
// after
String name = McpToolUtils.prefixedToolName("weatherServer", null, "get_forecast");
// -> weatherServer_get_forecast

if (!StringUtils.hasText(prefix) || !StringUtils.hasText(toolName)) {
    throw new IllegalArgumentException("prefix and toolName must be non-empty before calling prefixedToolName");
}

boolean validToolNameArgs(String prefix, String toolName) {
    return prefix != null && !prefix.isBlank() && toolName != null && !toolName.isBlank();
}

try {
    String name = McpToolUtils.prefixedToolName(prefix, title, toolName);
} catch (IllegalArgumentException e) {
    logger.error("Bad MCP tool naming inputs: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Calling McpToolUtils.prefixedToolName(prefix, title, toolName) directly with a null/empty prefix or toolName, or indirectly via McpToolUtils.getToolCallbacksFromMcpClients / tool callback providers with a client whose connectionNamePrefix is null/empty or where the server advertises a tool with a blank name.

Common situations: Constructing an MCP client without setting the connection name/prefix (the spring.ai.mcp.client.connections key left empty); calling the utility manually with "" as prefix; an MCP server registering a tool with an empty name (misbehaving server).

Related errors

• Updated resources list must not be null
• Failed to read stdio connection resource
• SSE connection '<connectionName>' requires a 'url' property.
• Failed to create SSE transport for connection '<connectionNa
• Error calling tool:

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/d12ea95fcc313938. Report an issue: GitHub.