alibaba/spring-ai-alibaba · error · BizException
ToolNameExists
ToolNameExists
Error message
Tool name already exists.
What it means
createTool in PluginServiceImpl throws BizException(TOOL_NAME_DUPLICATED) when getToolByName finds an existing tool with the same name under the same plugin in the workspace — tool names must be unique per plugin.
Source
Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/service/impl/PluginServiceImpl.java:276
return new PagingList<>(query.getCurrent(), query.getSize(), pageResult.getTotal(), plugins);
}
/**
* Creates a new tool for a plugin
* @param tool Tool information
* @return Generated tool ID
*/
@Override
public String createTool(Tool tool) {
try {
RequestContext context = RequestContextHolder.getRequestContext();
Plugin plugin = getPlugin(tool.getPluginId());
// check if tool name exists
ToolEntity toolEntity = getToolByName(context.getWorkspaceId(), plugin.getPluginId(), tool.getName());
if (toolEntity != null) {
throw new BizException(ErrorCode.TOOL_NAME_EXISTS.toError());
}
Tool.ToolConfig config = tool.getConfig();
List<ApiParameter> inputParams = config.getInputParams();
if (!CollectionUtils.isEmpty(inputParams)) {
for (ApiParameter apiParameter : inputParams) {
String location = apiParameter.getLocation();
if ("Get".equals(config.getRequestMethod()) && location.equals("Body")) {
throw new BizException(
ErrorCode.INVALID_PARAMS.toError("input_params", "Get method not support body params"));
}
}
}
// convert to swagger yaml
String yaml = OpenApiUtils.buildOpenAPIYaml(plugin, tool);
if (StringUtils.isBlank(yaml) || !CollectionUtils.isEmpty(OpenApiUtils.parseOpenAPIObject(yaml))) {View on GitHub (pinned to f82da0b50f)
Solutions
- Rename the tool to a unique name within the plugin
- Look up existing tool names under the plugin before creating
- Catch ToolNameExists BizException and surface a conflict message
Example fix
// before
tool.setName("get_weather");
pluginService.createTool(tool);
// after
String name = "get_weather";
int i = 2;
while (toolExists(pluginId, name)) { name = "get_weather_" + i++; }
tool.setName(name);
pluginService.createTool(tool); Defensive patterns
Strategy: validation
Validate before calling
// unique-name suggestion helper
String base = tool.getName(); String name = base; int i = 2;
while (toolNameExists(pluginId, name)) { name = base + "_" + i++; }
tool.setName(name); Try / catch
try {
pluginService.createTool(tool);
} catch (BizException e) {
throw new ResponseStatusException(HttpStatus.CONFLICT, "Tool name already exists");
} Prevention
- List existing tool names under the plugin before create
- Make create-tool requests idempotent on retry
- Enforce unique names in the UI form validation
- Avoid importing tools without deduplicating names
When it happens
Trigger: createTool(tool) where getToolByName(workspaceId, plugin.getPluginId(), tool.getName()) returns non-null.
Common situations: Retrying a create that already succeeded; copying a tool into the same plugin without renaming; importing tool definitions with colliding names.
Understand the failure class
Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.
Related errors
AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09).
Data as JSON: /api/errors/cd7d0d2f13290bc1.
Report an issue: GitHub.