alibaba/spring-ai-alibaba · error · BizException
CreateToolError
CreateToolError
Error message
Failed to create tool.
What it means
Generic wrapper thrown by createTool when any unexpected exception escapes the tool creation flow (and is not already a BizException). The original exception is attached as the cause, so the real failure (DB insert error, cache write failure, JSON serialization, etc.) must be read from the cause.
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:326
entity.setGmtCreate(new Date());
entity.setGmtModified(new Date());
entity.setCreator(context.getAccountId());
entity.setModifier(context.getAccountId());
toolMapper.insert(entity);
// cache it
String key = getToolCacheKey(entity.getWorkspaceId(), entity.getToolId());
redisManager.put(key, entity);
return toolId;
}
catch (BizException e) {
throw e;
}
catch (Exception e) {
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());View on GitHub (pinned to f82da0b50f)
Solutions
- Inspect the chained cause of this BizException in logs to identify the real underlying exception.
- Verify database connectivity and that the tool table schema matches the current entity (ToolEntity) columns.
- Ensure the tool config is JSON-serializable and not excessively large.
- Check Redis connectivity used by redisManager for tool caching.
- Retry createTool after fixing the infra issue; fix the payload if it is a data problem.
Example fix
// before: oversized config silently breaks insert
config.setLargeSchema(hugeYamlString); // > column size
toolService.createTool(context, tool);
// after: validate size first
if (hugeYamlString.length() > MAX_SCHEMA_LENGTH) {
throw new IllegalArgumentException("api schema too large");
}
toolService.createTool(context, tool); Defensive patterns
Strategy: try-catch
Validate before calling
// sanity-check payload before the call
if (tool.getName() == null || tool.getConfig() == null) {
throw new IllegalArgumentException("tool name and config are required");
} Try / catch
try {
toolService.createTool(context, tool);
} catch (BizException e) {
// CREATE_TOOL_ERROR wraps the real cause
log.error("createTool failed", e.getCause());
throw new IllegalStateException("tool creation failed", e.getCause());
} Prevention
- Always log/surface e.getCause() — the message is generic but the cause is specific.
- Keep tool config JSON within column size limits.
- Monitor DB and Redis health for the admin service.
- Apply schema migrations before deploying code that writes new entity fields.
When it happens
Trigger: Any non-BizException thrown inside createTool: toolMapper insert failure (constraint violation, DB down), Redis cache put failure, JsonUtils.toJson failure on the tool config, BeanCopierUtils.copy problems, or IdGenerator failures.
Common situations: Database unavailable or schema mismatch after version upgrade; oversized tool config JSON exceeding a column length; Redis connection issues; duplicate primary key generation collisions.
Understand the failure class
Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.
Related errors
AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09).
Data as JSON: /api/errors/11cba6efd69e2c4f.
Report an issue: GitHub.