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.
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.
Appendix: 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)