iflytek/astron-agent · error · BusinessException

TOOLBOX_CANNOT_DELETE_RELATED

TOOLBOX_CANNOT_DELETE_RELATED

Error message

BusinessException(ResponseEnum.TOOLBOX_CANNOT_DELETE_RELATED)

What it means

ToolBoxService.deleteTool throws TOOLBOX_CANNOT_DELETE_RELATED when botToolRelService.count finds at least one BotToolRel row referencing the tool's toolId, meaning the tool is used by one or more bots/agents (models). Like the workflow check, this blocks deletion of published tools that are still in use. The tool is only soft-deleted once no workflow or bot references remain.

Solutions

  1. Detach the tool from all bots (update each bot's tool configuration) and retry deletion.
  2. Query bot_tool_rel for the toolId to enumerate the blocking bots.
  3. Delete or reconfigure obsolete bots that reference the tool first.
  4. If the tool must go immediately, migrate bots to a replacement tool before deleting.

Example fix

// before
toolBoxService.deleteTool(toolId); // blocked by bot references
// after
long botRefs = botToolRelService.count(
    Wrappers.lambdaQuery(BotToolRel.class).eq(BotToolRel::getToolId, toolId));
if (botRefs == 0) {
    toolBoxService.deleteTool(toolId);
}
Defensive patterns

Strategy: validation

Validate before calling

long botRefs = botToolRelService.count(
    Wrappers.lambdaQuery(BotToolRel.class).eq(BotToolRel::getToolId, toolId));
if (botRefs > 0) { /* block delete; list blocking bots to the user */ }

Try / catch

try {
    toolBoxService.deleteTool(id);
} catch (BusinessException e) {
    if ("TOOLBOX_CANNOT_DELETE_RELATED".equals(e.getCode())) {
        // surface list of bots using this tool
    }
}

Prevention

When it happens

Trigger: Calling deleteTool for a published tool bound to a bot via bot_tool_rel; deleting a tool that an agent configured as its tool/plugin; cleanup of tools still attached to any bot in the space.

Common situations: User unaware a production bot still uses the tool; batch tool removal scripts that skip bot-reference checks; environment cloning where bot-tool relations persist even though the UI no longer shows them.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/fce2645425bccca5. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/tool/ToolBoxService.java:446

            throw new BusinessException(ResponseEnum.TOOLBOX_NOT_EXIST_DELETE);
        }
        dataPermissionCheckTool.checkToolBelong(toolBox);
        // Delete draft tools directly
        if (toolBox.getStatus().equals(0)) {
            toolBox.setDeleted(true);
            toolBox.setUpdateTime(new Timestamp(System.currentTimeMillis()));
            updateById(toolBox);
            return ApiResult.success();
        }

        long flowListCount = flowToolRelMapper.selectCount(Wrappers.lambdaQuery(FlowToolRel.class).eq(FlowToolRel::getToolId, toolBox.getToolId()));
        if (flowListCount > 0) {
            throw new BusinessException(ResponseEnum.TOOLBOX_CANNOT_DELETE_RELATED_WORKFLOW);
        }

        long modelListCount = botToolRelService.count(Wrappers.lambdaQuery(BotToolRel.class).eq(BotToolRel::getToolId, toolBox.getToolId()));
        if (modelListCount > 0) {
            throw new BusinessException(ResponseEnum.TOOLBOX_CANNOT_DELETE_RELATED);
        }

        toolBoxMapper.update(null, new UpdateWrapper<ToolBox>().lambda()
                .set(ToolBox::getDeleted, true)
                .set(ToolBox::getUpdateTime, new Timestamp(System.currentTimeMillis()))
                .eq(ToolBox::getToolId, toolBox.getToolId()));

        String paramStr = "?app_id=" + commonConfig.getAppId() + "&tool_ids=" + toolBox.getToolId();
        ToolResp toolDelResp = toolServiceCallHandler.toolDelete(paramStr);
        toolServiceCallHandler.dealResult(toolDelResp);
        return ApiResult.success();
    }

    public Object debugTool(Long id, JSONObject reqData) {
        ToolBox toolBox = getById(id);
        if (toolBox == null) {
            throw new BusinessException(ResponseEnum.TOOLBOX_NOT_EXIST);
        }

View on GitHub (pinned to 5e758547a8)