{"record":{"id":"d3ddd3d27e7bdefa","repo":"iflytek/astron-agent","slug":"tool-call-failed","errorCode":"TOOL_CALL_FAILED","errorMessage":"Tool run failed, toolId: {}, error: {}","messagePattern":"Tool run failed, toolId: (.+?), error: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/tool/AgentToolRuntimeService.java","lineNumber":150,"sourceCode":"            if (item == null || StringUtils.isBlank(item.getName())) {\n                continue;\n            }\n            Object value = assembleValue(item, args);\n            String location = StringUtils.lowerCase(StringUtils.defaultString(item.getLocation()));\n            switch (location) {\n                case \"header\" -> header.put(item.getName(), value);\n                case \"query\" -> query.put(item.getName(), value);\n                case \"path\" -> path.put(item.getName(), value);\n                default -> body.put(item.getName(), value);\n            }\n        }\n\n        ToolProtocolDto request = buildRequest(definition, header, query, path, body);\n        ToolProtocolDto response;\n        try {\n            response = toolServiceCallHandler.toolRun(request);\n        } catch (Exception e) {\n            log.warn(\"Tool run failed, toolId: {}, error: {}\", definition.getToolId(), e.getMessage());\n            return errorContent(\"TOOL_CALL_FAILED\", \"Tool call failed: \" + e.getMessage());\n        }\n        return extractResult(response);\n    }\n\n    private ToolProtocolDto buildRequest(AgentToolDefinition definition, JSONObject header, JSONObject query,\n            JSONObject path, JSONObject body) {\n        ToolHeader toolHeader = new ToolHeader();\n        toolHeader.setUid(definition.getUid());\n        toolHeader.setAppId(commonConfig.getAppId());\n\n        ToolParameter parameter = new ToolParameter();\n        parameter.setToolId(definition.getToolId());\n        parameter.setOperationId(definition.getOperationId());\n        parameter.setVersion(definition.getVersion());\n\n        Message message = new Message();\n        if (!header.isEmpty()) {","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/tool/AgentToolRuntimeService.java#L132-L168","documentation":"AgentToolRuntimeService.runTool builds a ToolProtocolDto request and delegates to toolServiceCallHandler.toolRun. Any exception thrown during the remote tool execution is caught, logged with the toolId, and converted into an error content payload with code TOOL_CALL_FAILED instead of propagating. It means the tool invocation itself failed (connection error, remote exception, protocol error), and the failure is returned as normal tool output content.","triggerScenarios":"toolServiceCallHandler.toolRun throws while executing a Link tool (callLinkTool path): network failure to the tool endpoint, timeout, remote 5xx, or serialization errors inside the handler.","commonSituations":"Link plugin service down or unreachable from the toolkit pod; tool endpoint timeout under load; bad tool definition (wrong URL/path template) causing handler exceptions; TLS/certificate issues in internal service calls.","solutions":["Inspect the logged `error: {}` message for the toolId to see the underlying exception","Verify the tool's endpoint configuration/definition (URL, auth headers) is correct and reachable from the service","Check the target tool service health (is the link/aitools plugin service running?)","Increase timeout or add retries for transient network failures","Surface the error content to the agent so it can retry or degrade gracefully"],"exampleFix":"// before\n} catch (Exception e) {\n    log.warn(\"Tool run failed, toolId: {}, error: {}\", definition.getToolId(), e.getMessage());\n    return errorContent(\"TOOL_CALL_FAILED\", \"Tool call failed: \" + e.getMessage());\n}\n// after\n} catch (Exception e) {\n    log.warn(\"Tool run failed, toolId: {}, error: {}\", definition.getToolId(), e.getMessage(), e);\n    return retryOnceOrErrorContent(definition, \"TOOL_CALL_FAILED\", e);\n}","handlingStrategy":"fallback","validationCode":"// verify definition is complete before calling\nif (definition == null || definition.getToolId() == null) return errorContent(\"TOOL_CALL_FAILED\", \"missing tool definition\");","typeGuard":null,"tryCatchPattern":"try { response = handler.toolRun(request); } catch (Exception e) { log.warn(\"tool {} failed\", id, e); return errorContent(\"TOOL_CALL_FAILED\", e.getMessage()); }","preventionTips":["Validate tool definitions (URL, headers) before registration","Add health checks for tool backend services","Set sane timeouts on the tool HTTP client","Return structured error content so agents can retry or degrade"],"tags":["tool-call","rpc","error-handling"],"backgroundTag":"api-request-failed","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}