alibaba/spring-ai-alibaba · error · BizException

PluginNameExists

PluginNameExists

Error message

Plugin name already exists.

What it means

Thrown by PluginServiceImpl.createPlugin when a plugin with the same name already exists in the current workspace. The service performs a name-uniqueness check (getPluginByName) before inserting and rejects duplicates.

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:93

	public PluginServiceImpl(ToolMapper toolMapper, RedisManager redisManager) {
		this.toolMapper = toolMapper;
		this.redisManager = redisManager;
	}

	/**
	 * Creates a new plugin
	 * @param plugin Plugin information
	 * @return Generated plugin ID
	 */
	@Override
	public String createPlugin(Plugin plugin) {
		try {
			RequestContext context = RequestContextHolder.getRequestContext();

			// check if plugin name exists
			PluginEntity pluginEntity = getPluginByName(context.getWorkspaceId(), plugin.getName());
			if (pluginEntity != null) {
				throw new BizException(ErrorCode.PLUGIN_NAME_EXISTS.toError());
			}

			String pluginId = IdGenerator.idStr();
			PluginEntity entity = BeanCopierUtils.copy(plugin, PluginEntity.class);
			entity.setPluginId(pluginId);
			entity.setWorkspaceId(context.getWorkspaceId());

			String config = JsonUtils.toJson(plugin.getConfig());
			entity.setConfig(config);
			entity.setType(PluginType.CUSTOM);
			entity.setStatus(PluginStatus.NORMAL);

			entity.setGmtCreate(new Date());
			entity.setGmtModified(new Date());
			entity.setCreator(context.getAccountId());
			entity.setModifier(context.getAccountId());

			this.save(entity);

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Rename the plugin to a unique name within the workspace
  2. Query existing plugin names first and handle the conflict in the caller
  3. Catch PluginNameExists BizException and surface a friendly conflict message

Example fix

// before
plugin.setName("weather");
pluginService.createPlugin(plugin);
// after
String name = "weather";
if (pluginService.getPluginByName(workspaceId, name) != null) {
    name = name + "-" + UUID.randomUUID().toString().substring(0, 6);
}
plugin.setName(name);
pluginService.createPlugin(plugin);
Defensive patterns

Strategy: try-catch

Validate before calling

if (pluginService.getPluginByName(workspaceId, plugin.getName()) != null) {
    plugin.setName(plugin.getName() + "-" + System.currentTimeMillis());
}

Try / catch

try {
    pluginService.createPlugin(plugin);
} catch (BizException e) {
    // name-conflict is user-fixable: return 409
    throw new ResponseStatusException(HttpStatus.CONFLICT, "Plugin name already exists");
}

Prevention

When it happens

Trigger: Calling createPlugin(plugin) with plugin.getName() matching an existing plugin in the same workspaceId.

Common situations: Retry of a create request that already succeeded; importing plugins from another workspace without renaming; UI/API allowing duplicate names under different casing.

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/9963082a1e3e97d0. Report an issue: GitHub.