alibaba/spring-ai-alibaba · error · BizException

ToolNotFound

ToolNotFound

Error message

Tool can not be found.

What it means

Not-found guard raised in PluginServiceImpl.updateTool. Before modifying a tool, the service looks it up via getToolById(workspaceId, toolId); when no matching tool entity exists in that workspace it throws a BizException with the TOOL_NOT_FOUND error code, since updates require an existing target. Typically caused by a stale or invalid toolId after the plugin was resynced or the tool was deleted. Callers should handle it as a 404-style business error.

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

			throw new BizException(ErrorCode.CREATE_TOOL_ERROR.toError(), e);
		}
	}

	/**
	 * Updates an existing tool
	 * @param tool Updated tool information
	 */
	@Override
	public void updateTool(Tool tool) {
		try {
			RequestContext context = RequestContextHolder.getRequestContext();

			String toolName = tool.getName();
			String pluginId = tool.getPluginId();

			ToolEntity entity = getToolById(context.getWorkspaceId(), tool.getToolId());
			if (entity == null) {
				throw new BizException(ErrorCode.TOOL_NOT_FOUND.toError());
			}

			Plugin plugin = getPlugin(pluginId);

			// check if tool name exists
			ToolEntity toolEntity = getToolByName(context.getWorkspaceId(), plugin.getPluginId(), toolName);
			if (toolEntity != null && !toolEntity.getId().equals(entity.getId())) {
				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"));

View on GitHub (pinned to f82da0b50f)

Solutions

1. Confirm the toolId exists by listing tools in the target workspace (getTools/plugin tool list) before updating.
2. Verify RequestContext.getWorkspaceId() matches the workspace that owns the tool.
3. Re-fetch the tool to obtain a fresh ID if it was deleted and recreated.
4. Handle BizException(ToolNotFound) in the caller with a clear user-facing message.

Example fix

// before: blind update with stale id
tool.setToolId(staleId);
toolService.updateTool(context, tool);

// after: check existence first
if (toolService.getTool(toolId) == null) { /* handle missing */ }
toolService.updateTool(context, tool);

// existence pre-check scoped to the workspace
ToolEntity existing = toolService.getToolByName(workspaceId, pluginId, tool.getName());
// or list tools and assert the id is present before updating
boolean exists = toolService.getTools(workspaceId, pluginId)
        .stream().anyMatch(t -> toolId.equals(t.getId()));
if (!exists) { throw new IllegalStateException("tool " + toolId + " not in workspace"); }

try {
    toolService.updateTool(context, tool);
} catch (BizException e) {
    if ("ToolNotFound".equals(e.getCode())) {
        // refresh local cache of tool ids; do not retry blindly
    } else { throw e; }
}

When it happens

Trigger: Calling PluginServiceImpl.updateTool with a toolId that was deleted, never existed, was created in a different workspace, or with an incorrect RequestContext workspaceId so the workspace-scoped lookup misses.

Common situations: Stale tool ID cached in client code after the tool was deleted; switching workspaces/environments while reusing IDs; typos in IDs passed from configuration.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• AppNotFound
• AppNotFound
• AppConfigNotFound
• ApiKeyNotFound
• AppVersionNotFound

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