{"record":{"id":"8e2e300ef9c4f643","repo":"alibaba/spring-ai-alibaba","slug":"tool-execution-error","errorCode":"TOOL_EXECUTION_ERROR","errorMessage":"TOOL_EXECUTION_ERROR: <e.getMessage()>","messagePattern":"TOOL_EXECUTION_ERROR: <e\\.getMessage\\(\\)>","errorType":"error_code","errorClass":"BizException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/service/impl/ToolExecutionServiceImpl.java","lineNumber":240,"sourceCode":"\n\t\t\t\treturn ToolExecutionResult.builder()\n\t\t\t\t\t.success(false)\n\t\t\t\t\t.error(Error.builder().statusCode(result.getCode()).message(result.getMessage()).build())\n\t\t\t\t\t.build();\n\n\t\t\t}\n\n\t\t\t// Map<String, Object> outputs =\n\t\t\t// buildOutputs(JsonUtils.fromJsonToMap(result.getResponse().toString()),\n\t\t\t// toolConfig.getOutputParams());\n\t\t\tString output = result.getResponse().toString();\n\t\t\treturn ToolExecutionResult.builder().success(true).output(output).build();\n\t\t}\n\t\tcatch (BizException e) {\n\t\t\tthrow e;\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new BizException(ErrorCode.TOOL_EXECUTION_ERROR.toError(e.getMessage()), e);\n\t\t}\n\t}\n\n\t/**\n\t * Validates the input parameters against the tool's configuration. Checks for\n\t * required parameters and their types.\n\t * @param request The tool execution request to validate\n\t */\n\tpublic void validateInputs(ToolExecutionRequest request) {\n\t\tList<ApiParameter> inputParams = request.getTool().getConfig().getInputParams();\n\t\tMap<String, Object> paramValues = request.getArguments();\n\t\tif (!CollectionUtils.isEmpty(inputParams)) {\n\t\t\tMap<String, ApiParameter> parameterMap = inputParams.stream()\n\t\t\t\t.filter(param -> StringUtils.isNotBlank(param.getKey()))\n\t\t\t\t.collect(Collectors.toMap(ApiParameter::getKey, Function.identity()));\n\t\t\tfor (Map.Entry<String, ApiParameter> entry : parameterMap.entrySet()) {\n\t\t\t\tObject paramValue = paramValues.get(entry.getKey());\n\t\t\t\tif (entry.getValue().isRequired() && paramValue == null) {","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/service/impl/ToolExecutionServiceImpl.java#L222-L258","documentation":"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).","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before\ncallTool(toolId, params); // raw exception surfaces as TOOL_EXECUTION_ERROR\n// after\ntry {\n    callTool(toolId, params);\n} catch (BizException e) {\n    if (\"TOOL_EXECUTION_ERROR\".equals(e.getCode())) {\n        log.error(\"Tool call failed: {}\", e.getMessage(), e.getCause());\n        // fall back or surface a user-friendly message\n    }\n}","handlingStrategy":"try-catch","validationCode":"if (toolConfig == null || !StringUtils.isNotBlank(toolConfig.getEndpoint())) { throw new IllegalStateException(\"Tool endpoint not configured\"); }","typeGuard":null,"tryCatchPattern":"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); } }","preventionTips":["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"],"tags":["tool-execution","http-client","wrapped-exception","admin-server"],"backgroundTag":"api-request-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}