alibaba/spring-ai-alibaba · error · IllegalArgumentException

Invalid Nacos config reference format: <nacosRef>. Expected

Error message

Invalid Nacos config reference format: <nacosRef>. Expected format: dataId/group

What it means

Thrown by NacosMcpGatewayToolCallback.resolveNacosReference when a placeholder value referencing a Nacos config is not in the required 'dataId/group' form (splitting on '/' must yield exactly two parts). It is an IllegalArgumentException indicating a malformed configuration expression in tool input or template.

Source

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

		return result.toString();
	}

	/**
	 * 解析Nacos引用
	 * @param nacosRef 引用字符串，格式为 dataId/group
	 * @param dotNotation 点语法部分，格式为 .key1.key2（可能为null）
	 * @return 解析后的值
	 */
	private String resolveNacosReference(String nacosRef, String dotNotation) {
		if (!org.springframework.util.StringUtils.hasText(nacosRef)) {
			return null;
		}

		try {
			// 解析dataId和group
			String[] configParts = nacosRef.split("/");
			if (configParts.length != 2) {
				throw new IllegalArgumentException(
						"Invalid Nacos config reference format: " + nacosRef + ". Expected format: dataId/group");
			}

			String dataId = configParts[0];
			String group = configParts[1];

			// 获取配置内容
			String configContent = getConfigContent(dataId, group);
			if (!org.springframework.util.StringUtils.hasText(configContent)) {
				logger.warn("[resolveNacosReference] No content found for dataId: {}, group: {}", dataId, group);
				return null;
			}

			// 如果没有点语法，直接返回配置内容
			if (!org.springframework.util.StringUtils.hasText(dotNotation)) {
				return configContent;
			}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Fix the reference string so it is exactly 'dataId/group' with one slash, e.g. 'my-service-config/DEFAULT_GROUP'.
2. If the group is DEFAULT_GROUP, write it explicitly rather than omitting it.
3. If the dataId contains slashes, use an escape/reference format supported by the library instead of a raw slash.
4. Validate all placeholder values in templates before invoking the tool.

Example fix

// before
String ref = "user-service-config"; // missing group
// after
String ref = "user-service-config/DEFAULT_GROUP";

boolean isValidNacosRef(String ref) {
    return ref != null && ref.split("/").length == 2 && !ref.isBlank() && !ref.startsWith("/") && !ref.endsWith("/");
}
// pre-check before invoking the tool
if (!isValidNacosRef(ref)) throw new IllegalArgumentException("Use dataId/group format: " + ref);

try {
    return callback.call(input);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid Nacos config reference format")) {
        logger.error("Fix placeholder to dataId/group: {}", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: A ${...} placeholder or nacosRef string containing zero or multiple '/' characters — e.g. 'myDataId' (missing group), 'dataId/group/extra', or 'a/b/c' — reaches resolveNacosReference during template replacement.

Common situations: Typos in Nacos references written into prompt/tool templates; groups or dataIds that themselves contain '/' characters; copying examples with the wrong separator.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Failed to resolve Nacos reference: <cause message>
• Nacos config content is not valid JSON, but dot notation was
• MissingParameter
• CreateMCPServerError
• UpdateMCPServerError

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