What causes "TOOL_EXECUTION_ERROR: " in alibaba/spring-ai-alibaba?

Read the wrapped exception message and cause (e.getMessage() is embedded in the BizException) to identify the actual failure.

alibaba/spring-ai-alibaba · error · BizException

TOOL_EXECUTION_ERROR

TOOL_EXECUTION_ERROR

Error message

TOOL_EXECUTION_ERROR: <e.getMessage()>

What it means

TOOL_EXECUTION_ERROR is the generic wrapper BizException thrown by ToolExecutionServiceImpl.callOpenApi when any unexpected Exception escapes during OpenAPI-style tool invocation. BizException subclasses are re-thrown unchanged; everything else (network failures, HTTP client errors, JSON parsing issues, runtime exceptions) is wrapped with the original exception message preserved. It signals the tool call itself failed, as opposed to input validation problems (which have their own codes).

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/ToolExecutionServiceImpl.java:240

				return ToolExecutionResult.builder()
					.success(false)
					.error(Error.builder().statusCode(result.getCode()).message(result.getMessage()).build())
					.build();

			}

			// Map<String, Object> outputs =
			// buildOutputs(JsonUtils.fromJsonToMap(result.getResponse().toString()),
			// toolConfig.getOutputParams());
			String output = result.getResponse().toString();
			return ToolExecutionResult.builder().success(true).output(output).build();
		}
		catch (BizException e) {
			throw e;
		}
		catch (Exception e) {
			throw new BizException(ErrorCode.TOOL_EXECUTION_ERROR.toError(e.getMessage()), e);
		}
	}

	/**
	 * Validates the input parameters against the tool's configuration. Checks for
	 * required parameters and their types.
	 * @param request The tool execution request to validate
	 */
	public void validateInputs(ToolExecutionRequest request) {
		List<ApiParameter> inputParams = request.getTool().getConfig().getInputParams();
		Map<String, Object> paramValues = request.getArguments();
		if (!CollectionUtils.isEmpty(inputParams)) {
			Map<String, ApiParameter> parameterMap = inputParams.stream()
				.filter(param -> StringUtils.isNotBlank(param.getKey()))
				.collect(Collectors.toMap(ApiParameter::getKey, Function.identity()));
			for (Map.Entry<String, ApiParameter> entry : parameterMap.entrySet()) {
				Object paramValue = paramValues.get(entry.getKey());
				if (entry.getValue().isRequired() && paramValue == null) {

View on GitHub (pinned to f82da0b50f)

Solutions

Read the wrapped exception message and cause (e.getMessage() is embedded in the BizException) to identify the actual failure.
Verify the tool's endpoint URL, method, and auth configuration in the admin tool definition.
Confirm the remote API is reachable from the server (curl the endpoint with the same parameters).
Check that tool input values pass validation (see TOOL_PARAMS_MISSING/INVALID) before execution.
If the remote API's response shape is unsupported, check server logs for parsing stack traces and update the tool schema.

Example fix

// before
callTool(toolId, params); // raw exception surfaces as TOOL_EXECUTION_ERROR
// after
try {
    callTool(toolId, params);
} catch (BizException e) {
    if ("TOOL_EXECUTION_ERROR".equals(e.getCode())) {
        log.error("Tool call failed: {}", e.getMessage(), e.getCause());
        // fall back or surface a user-friendly message
    }
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (toolConfig == null || !StringUtils.isNotBlank(toolConfig.getEndpoint())) { throw new IllegalStateException("Tool endpoint not configured"); }

Try / catch

try { ToolExecutionResult r = toolService.executeTool(toolId, params); } catch (BizException e) { if ("TOOL_EXECUTION_ERROR".equals(e.getCode())) { log.error("Tool execution failed: {}", e.getMessage(), e); } }

Prevention

Validate tool endpoint URL and auth config when saving the tool
Health-check remote endpoints before registering them
Log the full cause chain, not just getMessage()
Set explicit HTTP timeouts on the underlying client

When it happens

Trigger: Calling executeTool/callOpenApi for an OpenAPI tool where the remote HTTP endpoint is unreachable, returns a non-2xx response, times out, returns unparseable JSON, or where the HTTP client library throws any RuntimeException during request construction or response handling.

Common situations: Wrong or dead endpoint URL configured on the tool; DNS/network failures from the admin server; remote API requiring auth that was not configured; remote API returning an unexpected response body; a bug in request building (e.g. malformed query/header values).

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/8e2e300ef9c4f643. Report an issue: GitHub.